Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
36.9 KB
Raw Blame
// src/core/onboard/checks.ts
// sourcescope:file-brain-wide — every SQL site here is intentionally
// brain-wide aggregate. The onboard checks REPORT across all sources
// (orphan_count, stale_count, link_coverage, takes_count) so adding
// source_id WHERE clauses would change the semantic. Per A26.
//
// v0.41.18.0 (A16, T4). Four new doctor checks consumed by both:
//   - src/commands/doctor.ts runDoctor      (local surface)
//   - src/core/doctor-remote.ts             (thin-client surface)
//   - src/core/onboard/plan-from-checks.ts  (onboard remediation aggregator)
//
// Each helper is shaped: compute metric → return both Check entry (for
// doctor render) and RemediationStep[] (for onboard's extra-remediation
// plumbing per A2). Helpers stay PURE wrt config: no engine.connect, no
// process.exit. SQL via engine.executeRaw with `sourceScopeOpts(ctx)`
// when ctx threads — onboard surface threads explicitly per A26.

import { embedBackfillFix } from '../embed-consent.ts';
import { redactConnectionInfo } from '../audit/redact-connection-info.ts';
import type { BrainEngine } from '../engine.ts';
import type { RemediationStep } from '../remediation-step.ts';
import { makeRemediationStep } from '../remediation-step.ts';
import { QUARANTINE_FILTER_FRAGMENT } from '../quarantine.ts';
import { renderFragment, sqlFragment, trustedSql, type SqlFragment } from '../engine-sql/fragment.ts';
import { entityTypePredicateSql, resolveEntityTypes, type EntityTypeFilter, type EntityTypeResolution } from '../schema-pack/entity-types.ts';
import type { Action } from '../agent-output.ts';
import { embeddingEnablement, type ReadinessState } from '../readiness.ts';
import { embeddingsDisabled } from '../embedding-disabled.ts';
import { loadConfig } from '../config.ts';
import { MIN_ENTITY_PAGES_FOR_COVERAGE } from '../types.ts';
import { ORPHANED_ALIAS_COUNTS_SQL, SOFT_DELETED_ALIAS_COUNT_SQL } from '../repair/aliases.ts';
import { repairPreviewCommand } from '../repair/registry.ts';
import { isMissingSchemaObject } from '../utils.ts';

/** Shared shape returned by all four checks. */
export interface OnboardCheckResult {
  check: {
    name: string;
    status: 'ok' | 'warn' | 'fail';
    message: string;
    details?: Record<string, unknown>;
    /** Agent contract v1 (doctor E1/E2): see src/commands/doctor/check-fix.ts. */
    fix?: Action;
    severity?: 'info';
    readiness_state?: ReadinessState;
  };
  remediations: RemediationStep[];
}

/** Internal sql helper. Returns first row or empty object on throw. */
async function safeCount(engine: BrainEngine, sql: string, params: unknown[] = []): Promise<number> {
  try {
    const result = await engine.executeRaw(sql, params);
    const rows = (result as { rows?: Array<Record<string, unknown>> } | undefined)?.rows
      ?? (result as Array<Record<string, unknown>> | undefined)
      ?? [];
    const row = rows[0] ?? {};
    const raw = (row as Record<string, unknown>).count ?? (row as Record<string, unknown>).c ?? 0;
    const n = Number(raw);
    return Number.isFinite(n) ? n : 0;
  } catch {
    return 0;
  }
}

/** #4772: a live, visible page whose type the active pack(s) declare as an entity, per source (the get_health predicate). */
function visibleEntityPredicate(filter: EntityTypeFilter): SqlFragment {
  return sqlFragment`${entityTypePredicateSql('p', filter)} AND p.deleted_at IS NULL AND ${trustedSql(QUARANTINE_FILTER_FRAGMENT)}`;
}

/**
 * A pack in scope did not load, so the entity population is unknown: a warn
 * with `entity_types_unavailable`, never a coverage read over an empty or
 * legacy list.
 */
function entityTypesUnavailableResult(name: string, resolution: Extract<EntityTypeResolution, { status: 'pack_unavailable' }>): OnboardCheckResult {
  const where = resolution.unresolved.filter(Boolean);
  return {
    check: {
      name, status: 'warn',
      message: `Entity types unknown: could not resolve the active schema pack${where.length ? ` for source${where.length > 1 ? 's' : ''} ${where.map((id) => `'${id}'`).join(', ')}` : ''}, so ${name} cannot be graded. Run \`gbrain schema active --json\` to debug.`,
      details: { code: 'entity_types_unavailable', entity_types_status: 'pack_unavailable', unresolved_sources: where },
      fix: { argv: ['gbrain', 'schema', 'active', '--json', ...(where.length ? ['--source', where[0]!] : [])], consent: [], actor: 'agent', requires_exclusive: false,
        why: 'Read-only: shows which pack is active, the tier it comes from and why it did not load.', verify: { argv: ['gbrain', 'doctor', '--only', name, '--json'] } },
    },
    remediations: [],
  };
}

/** Count the visible entity pages under `filter`. */
async function countVisibleEntities(engine: BrainEngine, filter: EntityTypeFilter): Promise<number> {
  const sql = renderFragment(sqlFragment`SELECT COUNT(*) AS count FROM pages p WHERE ${visibleEntityPredicate(filter)}`);
  return safeCount(engine, sql.text, sql.params);
}

/**
 * Coverage is a ratio over the visible entity population, and below
 * MIN_ENTITY_PAGES_FOR_COVERAGE that ratio is noise: BrainHealth reports
 * null there, so a warn from these checks would contradict it and could never
 * be cleared by extraction. Returns the not-applicable `ok` result for an
 * ungraded population, or null when the caller should compute coverage.
 */
function ungradedCoverageResult(name: string, entityPages: number): OnboardCheckResult | null {
  if (entityPages >= MIN_ENTITY_PAGES_FOR_COVERAGE) return null;
  const message = entityPages === 0
    ? 'No entity pages — coverage check vacuous'
    : `Only ${entityPages} entity ${entityPages === 1 ? 'page' : 'pages'} (< ${MIN_ENTITY_PAGES_FOR_COVERAGE}) — coverage ratio not meaningful at this scale`;
  return { check: { name, status: 'ok', message }, remediations: [] };
}

export type CoverageFeature =
  | { table: 'links'; pageIdColumn: 'to_page_id' }
  | { table: 'timeline_entries'; pageIdColumn: 'page_id' };

/** entity_link_coverage counts inbound links; timeline_coverage counts timeline entries. */
export const LINK_COVERAGE_FEATURE: CoverageFeature = { table: 'links', pageIdColumn: 'to_page_id' };
export const TIMELINE_COVERAGE_FEATURE: CoverageFeature = { table: 'timeline_entries', pageIdColumn: 'page_id' };

/**
 * One row `{ sample_size, matched }`: the visible entity pages (optionally
 * TABLESAMPLEd) and how many of them have `feature`. The coverage checks and
 * remediation impact capture both read coverage through this query, so a
 * `gbrain onboard --history` row measures the population the check grades.
 */
export function visibleEntityCoverageSql(feature: CoverageFeature, filter: EntityTypeFilter, sampleClause = ''): { text: string; params: unknown[] } {
  return renderFragment(sqlFragment`WITH sampled_entities AS (
         SELECT p.id
           FROM pages p ${trustedSql(sampleClause)}
          WHERE ${visibleEntityPredicate(filter)}
       )
       SELECT
         COUNT(*)::int AS sample_size,
         COUNT(*) FILTER (
           WHERE EXISTS (
             SELECT 1
               FROM ${trustedSql(feature.table)} f
              WHERE f.${trustedSql(feature.pageIdColumn)} = s.id
           )
         )::int AS matched
         FROM sampled_entities s`);
}

interface EntityCoverageSample {
  matched: number;
  sampleSize: number;
}

/** Parse a SQL count defensively: coverage is an operator-facing health metric,
 * so a malformed driver value must not escape as NaN or a negative count. */
function finiteCount(value: unknown): number {
  const n = Number(value);
  return Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0;
}

/**
 * Count the feature numerator and denominator from the SAME sampled CTE.
 * TABLESAMPLE BERNOULLI returns a random number of rows; deriving its
 * denominator from `total * requestedPercent` can make coverage exceed 100%.
 */
async function sampleVisibleEntityCoverage(
  engine: BrainEngine,
  sampleClause: string,
  feature: CoverageFeature,
  filter: EntityTypeFilter,
): Promise<EntityCoverageSample | { error: string }> {
  try {
    const sql = visibleEntityCoverageSql(feature, filter, sampleClause);
    const result = await engine.executeRaw(sql.text, sql.params);
    const rows = (result as { rows?: Array<Record<string, unknown>> } | undefined)?.rows
      ?? (result as Array<Record<string, unknown>> | undefined)
      ?? [];
    const row = rows[0] ?? {};
    const sampleSize = finiteCount(row.sample_size);
    // The SQL shape guarantees matched <= sample_size. Keep a defensive clamp
    // at the rendering boundary so a driver/fixture anomaly still cannot emit
    // impossible percentages or feed a negative value into sqrt().
    const matched = Math.min(sampleSize, finiteCount(row.matched));
    return { matched, sampleSize };
  } catch (error) {
    return { error: redactConnectionInfo(error instanceof Error ? error.message : String(error)) };
  }
}

/** #7145: a coverage read that failed or sampled no row measured nothing, so it is not "0% coverage". */
function unmeasuredCoverage(name: string, sample: EntityCoverageSample | { error: string }): OnboardCheckResult {
  const why = 'error' in sample ? `the coverage read failed (${sample.error})` : 'the sampled read returned no entity page';
  return { check: { name, status: 'warn', message: `Coverage unknown: ${why}; rerun doctor.`, details: { health: 'unknown', reason: 'error' in sample ? 'error' : 'empty_sample' } }, remediations: [] };
}

function coverageWithConfidence(sample: EntityCoverageSample): { coverage: number; ci: number } {
  const rawCoverage = sample.sampleSize > 0 ? sample.matched / sample.sampleSize : 0;
  const coverage = Math.min(1, Math.max(0, rawCoverage));
  const variance = Math.max(0, coverage * (1 - coverage));
  const ci = Math.sqrt(variance / Math.max(1, sample.sampleSize));
  return { coverage, ci };
}

/**
 * embed_staleness: count of chunks awaiting embedding.
 *
 * Uses `engine.countStaleChunks()`, the embed worker's own predicate (the
 * registry-active embedding column plus its embed_skip/quarantine
 * exclusions), so the check and the worker agree. A failed count is "not
 * verified" (#5432), never "No stale chunks".
 */
export async function checkEmbedStaleness(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  if (await embeddingsDisabled(engine)) {
    const cfg = loadConfig();
    return {
      check: {
        name: 'embed_staleness', status: 'ok', severity: 'info', readiness_state: 'disabled_by_choice',
        message: 'Not applicable: embeddings are disabled on this brain by choice, so chunks have no vectors by design (keyword search keeps working).',
        ...(cfg ? { fix: embeddingEnablement(cfg) } : {}),
      },
      remediations: [],
    };
  }
  let staleCount: number;
  try {
    staleCount = await engine.countStaleChunks();
  } catch (e) {
    const reason = redactConnectionInfo(e instanceof Error ? e.message : String(e)).slice(0, 200);
    return {
      check: {
        name: 'embed_staleness',
        status: 'warn',
        message: `Not verified: the stale-chunk count failed (${reason}). Fix the cause, then re-run \`gbrain doctor\`.`,
        details: { code: 'not_verified', verified: false, reason, fix: 'gbrain doctor', docs: 'docs/guides/troubleshooting.md#not-verified-doctor-checks' },
      },
      remediations: [],
    };
  }
  const remediations: RemediationStep[] = [];
  let status: 'ok' | 'warn' | 'fail' = 'ok';
  let message: string;

  if (staleCount === 0) {
    message = 'No stale chunks';
  } else if (staleCount < 1000) {
    status = 'warn';
    message = `${staleCount} stale chunks (small backlog)`;
    remediations.push(makeRemediationStep({
      id: 'onboard.embed_catch_up',
      job: 'embed-catch-up',
      params: { batchSize: 500 },
      severity: 'medium',
      est_seconds: Math.min(900, Math.ceil(staleCount * 0.2)),
      est_usd_cost: staleCount * 0.00002,
      rationale: `${staleCount} chunks awaiting embedding`,
      status: 'remediable',
    }));
  } else {
    // v0.41.18.0: warn-only even on large backlogs. Doctor exit code should
    // not flip from a brain that has pages waiting to be embedded — that's
    // a "needs work" condition, not a "broken" one. The high-severity
    // remediation still surfaces via onboard's plan.
    status = 'warn';
    message = `${staleCount} stale chunks (large backlog — vector search returning outdated content)`;
    remediations.push(makeRemediationStep({
      id: 'onboard.embed_catch_up',
      job: 'embed-catch-up',
      params: { batchSize: 1000, priority: 'recent' },
      severity: 'high',
      est_seconds: Math.min(3600, Math.ceil(staleCount * 0.2)),
      est_usd_cost: staleCount * 0.00002,
      rationale: `${staleCount} chunks awaiting embedding; recent-first catch-up`,
      status: 'remediable',
    }));
  }
  return {
    check: { name: 'embed_staleness', status, message, ...(staleCount > 0 ? { fix: embedBackfillFix({ backlog: staleCount, verifyCheck: 'embed_staleness' }) } : {}) },
    remediations,
  };
}

/**
 * Can `extract-ner` actually do anything on this brain?
 *
 * Three-state on purpose. The recommender must be able to tell "the pack
 * declares no NER rules" (a real, explainable no-auto-fix) from "the pack
 * could not be resolved at all" (an operator problem). Collapsing both into
 * a bare `false` is what turns a phantom recommendation into a phantom
 * SILENCE: the nag disappears and nothing says why.
 *
 * Resolution goes through `loadActivePackForLocalEngine`, which is also what
 * the `extract-ner` handler uses — so recommender and handler cannot resolve
 * different packs and then disagree about the same brain. That helper pins
 * `remote: false` (an onboard check is a LOCAL surface; the generic
 * `loadActivePackBestEffort` defaults `remote: ctx.remote ?? true`, and a
 * tier-1 trust rejection would arrive here masquerading as "pack has no NER
 * rules") and pairs file-only config with the engine's DB-side `schema_pack`,
 * matching `checkPackUpgradeAvailable` / `checkTypeProliferation` below.
 *
 * Those two siblings still open-code the same resolution rather than calling
 * the shared helper: their outer `catch` returns a distinguishable
 * `Check skipped: <message>`, which a null-swallowing helper would flatten
 * into "No active pack".
 */
async function resolveNerInferenceCapability(
  engine: BrainEngine,
): Promise<'supported' | 'no_rules' | 'unresolved'> {
  try {
    const { loadActivePackForLocalEngine, packSupportsNerInference } =
      await import('../schema-pack/best-effort.ts');
    const pack = await loadActivePackForLocalEngine(engine);
    if (!pack) return 'unresolved';
    return packSupportsNerInference(pack) ? 'supported' : 'no_rules';
  } catch {
    return 'unresolved';
  }
}

/**
 * entity_link_coverage: fraction of entity pages with at least one inbound link.
 *
 * Per A21 + codex finding #15: TABLESAMPLE BERNOULLI on Postgres when
 * total_pages > 50K, with pinned sample rate (LEAST 100, GREATEST 2,
 * targeting ~5000 sampled rows). PGLite path: full scan.
 *
 * The ±sqrt(p(1-p)/n) confidence interval is embedded in the message
 * itself so doctor + onboard render show "coverage: 31% ± 1.3%" not
 * a misleading point estimate.
 */
export async function checkEntityLinkCoverage(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  // Total visible entity pages. Quarantined pages are hidden from the brain,
  // so they are outside both the coverage numerator and denominator.
  const entityTypes = await resolveEntityTypes(engine, null);
  if (entityTypes.status === 'pack_unavailable') return entityTypesUnavailableResult('entity_link_coverage', entityTypes);
  const totalEntities = await countVisibleEntities(engine, entityTypes.filter);

  const ungraded = ungradedCoverageResult('entity_link_coverage', totalEntities);
  if (ungraded) return ungraded;

  // Decide TABLESAMPLE policy (PG only, when >50K entities)
  const useSample = engine.kind === 'postgres' && totalEntities > 50_000;
  const samplePct = useSample
    ? Math.max(2.0, Math.min(100.0, (5000.0 / totalEntities) * 100))
    : 100;
  const sampleClause = useSample ? `TABLESAMPLE BERNOULLI (${samplePct.toFixed(2)})` : '';

  const sample = await sampleVisibleEntityCoverage(
    engine,
    sampleClause,
    LINK_COVERAGE_FEATURE,
    entityTypes.filter,
  );
  if ('error' in sample || sample.sampleSize === 0) return unmeasuredCoverage('entity_link_coverage', sample);
  const { coverage, ci } = coverageWithConfidence(sample);

  const pct = Math.round(coverage * 100);
  const ciPct = (ci * 100).toFixed(1);
  const sampleNote = useSample ? ` (sampled ${samplePct.toFixed(1)}%)` : '';

  const remediations: RemediationStep[] = [];
  let status: 'ok' | 'warn' | 'fail' = 'ok';
  let message: string;

  // v0.41.18.0: warn-only, never fail. Empty entity link coverage is "needs
  // work" not "broken" — doctor's exit code should not flip from a fresh
  // brain with entity pages but no auto-extracted links yet. Fail status
  // would break `gbrain doctor exits 0` contract; the recommendation
  // surfaces the same fix via the onboard plan either way.
  if (coverage >= 0.7) {
    message = `Coverage ${pct}% ± ${ciPct}%${sampleNote}`;
  } else {
    status = 'warn';
    message = `Coverage ${pct}% ± ${ciPct}% (target 70%)${sampleNote}`;
    // Only recommend NER extraction if the active pack actually declares
    // inference.regex rules — otherwise `extract-ner` is a structural no-op
    // (pack_unavailable, 0 links) and the recommendation could never clear.
    //
    // Recommender and handler now share BOTH halves of the question: the same
    // resolver (`loadActivePackForLocalEngine`) picks the pack, and the same
    // predicate (`packSupportsNerInference`) judges its capability. Sharing
    // only the predicate would still have let the two resolve different packs.
    const nerCapability = await resolveNerInferenceCapability(engine);
    if (nerCapability === 'supported') {
      remediations.push(makeRemediationStep({
        id: 'onboard.extract_ner_links',
        job: 'extract-ner',
        params: {},
        severity: coverage >= 0.4 ? 'medium' : 'high',
        est_seconds: coverage >= 0.4 ? 300 : 600,
        est_usd_cost: 0,
        rationale: `Entity link coverage at ${pct}%; NER extraction lifts typed-link density`,
        status: 'remediable',
      }));
    } else if (nerCapability === 'no_rules') {
      message += ' — no auto-fix: the active schema pack declares no NER inference rules'
        + ' (add link_types[].inference.regex, or upgrade the pack)';
    } else {
      message += ' — no auto-fix: could not resolve the active schema pack, so NER'
        + ' capability is unknown (see `gbrain doctor` schema_pack checks)';
    }
  }
  return {
    check: { name: 'entity_link_coverage', status, message },
    remediations,
  };
}

/**
 * timeline_coverage: fraction of entity pages with at least one timeline entry.
 *
 * Same TABLESAMPLE policy as entity_link_coverage for big brains.
 */
export async function checkTimelineCoverage(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  const entityTypes = await resolveEntityTypes(engine, null);
  if (entityTypes.status === 'pack_unavailable') return entityTypesUnavailableResult('timeline_coverage', entityTypes);
  const totalEntities = await countVisibleEntities(engine, entityTypes.filter);

  const ungraded = ungradedCoverageResult('timeline_coverage', totalEntities);
  if (ungraded) return ungraded;

  const useSample = engine.kind === 'postgres' && totalEntities > 50_000;
  const samplePct = useSample
    ? Math.max(2.0, Math.min(100.0, (5000.0 / totalEntities) * 100))
    : 100;
  const sampleClause = useSample ? `TABLESAMPLE BERNOULLI (${samplePct.toFixed(2)})` : '';

  const sample = await sampleVisibleEntityCoverage(
    engine,
    sampleClause,
    TIMELINE_COVERAGE_FEATURE,
    entityTypes.filter,
  );
  if ('error' in sample || sample.sampleSize === 0) return unmeasuredCoverage('timeline_coverage', sample);
  const { coverage, ci } = coverageWithConfidence(sample);
  const pct = Math.round(coverage * 100);
  const ciPct = (ci * 100).toFixed(1);
  const sampleNote = useSample ? ` (sampled ${samplePct.toFixed(1)}%)` : '';

  const remediations: RemediationStep[] = [];
  let status: 'ok' | 'warn' | 'fail' = 'ok';
  let message: string;

  // v0.41.18.0: warn-only, never fail. Same posture as entity_link_coverage —
  // the recommendation still surfaces in onboard's plan, but doctor exit
  // code doesn't flip on a fresh brain.
  if (coverage >= 0.9) {
    message = `Coverage ${pct}% ± ${ciPct}%${sampleNote}`;
  } else {
    status = 'warn';
    message = `Coverage ${pct}% ± ${ciPct}% (target 90%)${sampleNote}`;
    // Only recommend meeting-derived timeline extraction if there are dated
    // meeting pages to extract FROM — otherwise the job creates 0 entries
    // (it skips meetings without effective_date) and the rec never clears.
    const datableMeetings = await safeCount(
      engine,
      `SELECT COUNT(*) AS count FROM pages
         WHERE type = 'meeting' AND effective_date IS NOT NULL AND deleted_at IS NULL`,
    );
    if (datableMeetings > 0) {
      remediations.push(makeRemediationStep({
        id: 'onboard.extract_timeline_from_meetings',
        job: 'extract-timeline-from-meetings',
        params: {},
        severity: coverage >= 0.7 ? 'medium' : 'high',
        est_seconds: coverage >= 0.7 ? 240 : 480,
        est_usd_cost: 0,
        rationale: `Timeline coverage at ${pct}%; meeting-derived entries lift it`,
        status: 'remediable',
      }));
    } else {
      message += ' — no auto-fix: no dated meeting pages to extract timeline entries from';
    }
  }
  return {
    check: { name: 'timeline_coverage', status, message },
    remediations,
  };
}

/**
 * takes_count: number of takes (typed claims) in the brain.
 *
 * Per A12 two-gate consent: the remediation only emits when
 * `takes.bootstrap_enabled` config is true. Otherwise the check shows
 * a status + hint, but no autopilot-eligible remediation.
 */
export async function checkTakesCount(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  const takesCount = await safeCount(
    engine,
    `SELECT COUNT(*) AS count FROM takes`,
  );

  let bootstrapEnabled = false;
  try {
    const cfg = await engine.getConfig('takes.bootstrap_enabled');
    bootstrapEnabled = cfg === 'true' || cfg === '1';
  } catch {
    bootstrapEnabled = false;
  }

  const remediations: RemediationStep[] = [];
  let status: 'ok' | 'warn' | 'fail' = 'ok';
  let message: string;

  if (takesCount >= 100) {
    message = `${takesCount} takes (calibration ready)`;
  } else if (takesCount === 0) {
    status = 'warn';
    if (bootstrapEnabled) {
      message = `0 takes (bootstrap eligible — gbrain takes extract --from-pages)`;
      remediations.push(makeRemediationStep({
        id: 'onboard.takes_bootstrap',
        job: 'extract-takes-from-pages',
        protected: true,
        params: {},
        severity: 'medium',
        est_seconds: 1800,
        est_usd_cost: 5.00,
        rationale: '0 takes; LLM-bearing extraction over concept/atom/lore pages',
        status: 'remediable',
      }));
    } else {
      return {
        check: {
          name: 'takes_count', status: 'ok', severity: 'info', readiness_state: 'disabled_by_choice',
          message: '0 takes (takes.bootstrap_enabled is false; opt in to enable)',
          fix: {
            argv: ['gbrain', 'config', 'set', 'takes.bootstrap_enabled', 'true'], consent: ['paid'], actor: 'agent', requires_exclusive: false,
            why: 'Takes (typed claims) are opt-in. Enabling the bootstrap lets maintenance extract them from existing pages with a chat model (about $5 on a typical brain), which feeds calibration.',
            user_message: 'gbrain can extract typed claims ("takes") from your pages so it can track calibration over time. It uses a paid chat model (roughly $5 once). Turn it on?',
            verify: { argv: ['gbrain', 'doctor', '--only', 'takes_count', '--json'] },
          },
        },
        remediations,
      };
    }
  } else {
    message = `${takesCount} takes (calibration usable; >100 ideal)`;
  }
  return {
    check: { name: 'takes_count', status, message },
    remediations,
  };
}

/**
 * Run all four checks in parallel; aggregate into a single payload.
 * Consumed by onboard's plan generation + (later) doctor's runDoctor.
 *
 * Per A20: callers can race this against an AbortSignal-bound timer for
 * partial-results fallthrough. Each individual safeCount() returns 0
 * on throw so a single check failure doesn't break the aggregate.
 */
export async function runAllOnboardChecks(
  engine: BrainEngine,
): Promise<OnboardCheckResult[]> {
  return Promise.all([
    checkEmbedStaleness(engine),
    checkEntityLinkCoverage(engine),
    checkTimelineCoverage(engine),
    checkTakesCount(engine),
    // v0.42 type-unification (T13-T15): 3 new checks added to onboard.
    checkPackUpgradeAvailable(engine),
    checkTypeProliferation(engine),
    checkDanglingAliases(engine),
  ]);
}

// ===========================================================================
// v0.42 Type Unification (T13-T15) — 3 onboard checks
// ===========================================================================

/**
 * pack_upgrade_available: fires when the active schema pack has a successor
 * pack declared via `migration_from`. v0.42 ships gbrain-base-v2 as the
 * declared successor of [email protected]. Emits a manual_only RemediationStep
 * (D17) targeting the unify-types Minion handler.
 */
export async function checkPackUpgradeAvailable(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  try {
    const { loadActivePack, findPackSuccessors } = await import('../schema-pack/load-active.ts');
    const { loadConfigFileOnly } = await import('../config.ts');
    // Read the engine's DB-side schema_pack so a post-unify flip is visible
    // here even before the file-plane config catches up. File-only config
    // preserves tier-6 schema_pack without merging transient env/database state.
    let dbConfig: string | undefined;
    try {
      dbConfig = (await engine.getConfig('schema_pack')) ?? undefined;
    } catch { /* engine.config may not exist on very old brains */ }
    const active = await loadActivePack({ cfg: loadConfigFileOnly(), remote: false, dbConfig })
      .catch(() => null);
    if (!active) {
      return {
        check: { name: 'pack_upgrade_available', status: 'ok', message: 'No active pack' },
        remediations: [],
      };
    }
    const successors = await findPackSuccessors(active.manifest.name, active.manifest.version);
    if (successors.length === 0) {
      return {
        check: {
          name: 'pack_upgrade_available',
          status: 'ok',
          message: `Active pack ${active.identity} is current (no successor declared)`,
        },
        remediations: [],
      };
    }
    const successor = successors[0];
    const { managedPersistenceEnabled } = await import('../persistence/ownership.ts');
    if (await managedPersistenceEnabled(engine)) {
      // #6196: retype runs outside the persistence coordinator, so a managed brain cannot run the apply job.
      return {
        check: {
          name: 'pack_upgrade_available', status: 'ok', severity: 'info', readiness_state: 'degraded',
          message: `Active pack: ${active.identity}. Successor available: ${successor.identity}. On a managed brain unify-types switches the pack only when no page needs retyping, linking or aliasing; coordinated retype is not available yet, so do not submit the apply job while the preview shows pages to change. Preview: \`gbrain onboard --check --explain\``,
          fix: { argv: ['gbrain', 'onboard', '--check', '--explain'], consent: [], actor: 'agent', requires_exclusive: false,
            why: 'Previews the pack upgrade read-only. Applying it on a managed brain waits for coordinated retype unless the preview shows nothing to change.' },
        },
        remediations: [],
      };
    }
    return {
      check: {
        name: 'pack_upgrade_available',
        status: 'warn',
        message:
          `Active pack: ${active.identity}. Successor available: ${successor.identity}. ` +
          `Preview: \`gbrain onboard --check --explain\``,
      },
      remediations: [
        makeRemediationStep({
          id: 'onboard.pack_upgrade_' + successor.manifest.name,
          job: 'unify-types',
          // #1575: the worker defaults `apply` to false (dry-run); a
          // remediation step is a consented apply, so carry it explicitly.
          params: { target_pack: successor.manifest.name, apply: true },
          severity: 'medium',
          est_seconds: 600,  // ~10min on 186K-page brain (production proxy)
          est_usd_cost: 0,   // pure SQL; no LLM spend
          protected: true,   // PROTECTED handler; manual-only by job name (remediation/manual-only.ts)
          rationale:
            `Pack upgrade ${active.manifest.name} → ${successor.manifest.name}; ` +
            `collapses redundant page types into the new canonical taxonomy. ` +
            `Reversible via 72h soft-delete TTL on alias/link pages + ` +
            `frontmatter.legacy_type preservation on retyped pages.`,
          status: 'remediable',
        }),
      ],
    };
  } catch (e) {
    return {
      check: {
        name: 'pack_upgrade_available',
        status: 'ok',
        message: `Check skipped: ${(e as Error).message}`,
      },
      remediations: [],
    };
  }
}

const PAGE_TYPE_PAIRS_SQL = `WITH RECURSIVE pairs AS (
  (SELECT source_id, type FROM pages WHERE deleted_at IS NULL AND type IS NOT NULL ORDER BY source_id, type LIMIT 1)
  UNION ALL
  SELECT n.source_id, n.type FROM pairs, LATERAL (
    SELECT p.source_id, p.type FROM pages p
     WHERE p.deleted_at IS NULL AND p.type IS NOT NULL AND (p.source_id, p.type) > (pairs.source_id, pairs.type)
     ORDER BY p.source_id, p.type LIMIT 1) n
)
SELECT source_id, type FROM pairs`;

/**
 * type_proliferation (D16): pack-aware ratio. Warns when distinct typed
 * pages exceed pack-declared types + 5; fails at declared × 2. No false
 * positives on custom packs (compares to actual pack declaration count,
 * not a hardcoded threshold).
 *
 * #6289: each source is graded against its own resolved pack (per-source
 * DB config included); sources sharing a pack pool their labels, and an
 * alias counts as its canonical type. A source whose pack does not resolve,
 * or a failed query, is "not verified" (warn), never ok.
 *
 * The (source, type) pairs are read by a skip scan over idx_pages_source_type
 * (v316): one index probe per distinct pair, never a pass over every page.
 */
export async function checkTypeProliferation(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  const result = (status: 'ok' | 'warn' | 'fail', message: string): OnboardCheckResult =>
    ({ check: { name: 'type_proliferation', status, message }, remediations: [] });
  let rows: Array<{ source_id: string; type: string }>;
  try {
    rows = await engine.executeRaw<{ source_id: string; type: string }>(PAGE_TYPE_PAIRS_SQL);
  } catch (e) {
    return result('warn', `type_proliferation not verified: the page type query failed (${(e as Error).message}).`);
  }
  const { loadActivePackForLocalEngine } = await import('../schema-pack/best-effort.ts');
  const { classifyStoredType } = await import('../schema-pack/type-usage.ts');
  const pools = new Map<string, { pack: NonNullable<Awaited<ReturnType<typeof loadActivePackForLocalEngine>>>; sources: Set<string>; labels: Set<string>; undeclared: Set<string> }>();
  const unresolved = new Set<string>();
  for (const sourceId of new Set(rows.map(r => r.source_id))) {
    const pack = await loadActivePackForLocalEngine(engine, { sourceId });
    if (!pack) { unresolved.add(sourceId); continue; }
    const pool = pools.get(pack.identity) ?? { pack, sources: new Set<string>(), labels: new Set<string>(), undeclared: new Set<string>() };
    pool.sources.add(sourceId);
    for (const { type } of rows.filter(r => r.source_id === sourceId)) {
      const cls = classifyStoredType(type, pack.manifest);
      pool.labels.add(cls.kind === 'alias_of' ? cls.canonical : type);
      if (cls.kind === 'undeclared') pool.undeclared.add(type);
    }
    pools.set(pack.identity, pool);
  }
  const graded = [...pools.values()].map(pool => {
    const declared = pool.pack.manifest.page_types.length;
    const n = pool.labels.size;
    return { pool, declared, n, status: n > declared * 2 ? 'fail' as const : n > declared + 5 ? 'warn' as const : 'ok' as const };
  });
  const rank = { ok: 0, warn: 1, fail: 2 };
  const worst = graded.sort((a, b) => rank[b.status] - rank[a.status] || b.n - b.declared - (a.n - a.declared))[0];
  const where = (g: typeof graded[number]) => {
    const undeclared = [...g.pool.undeclared].sort();
    const names = undeclared.slice(0, 5).join(', ') + (undeclared.length > 5 ? `, +${undeclared.length - 5} more` : '');
    return ` (source${g.pool.sources.size > 1 ? 's' : ''} ${[...g.pool.sources].sort().join(', ')}, pack ${g.pool.pack.manifest.name}${names ? `; undeclared: ${names}` : ''})`;
  };
  const notVerified = unresolved.size
    ? ` Not verified: the schema pack for source${unresolved.size > 1 ? 's' : ''} ${[...unresolved].sort().join(', ')} does not resolve (run \`gbrain schema active --source <id>\`).`
    : '';
  if (worst?.status === 'fail') {
    return result('fail',
      `${worst.n} distinct page types (pack declares ${worst.declared})${where(worst)}. ` +
      `Run \`gbrain onboard --check --explain\` to preview a pack upgrade ` +
      `or define a custom pack with mapping_rules.${notVerified}`);
  }
  if (worst?.status === 'warn') {
    return result('warn', `${worst.n} distinct page types vs ${worst.declared} declared in pack — consider unification${where(worst)}.${notVerified}`);
  }
  if (notVerified) return result('warn', `type_proliferation${notVerified.trimEnd()}`);
  if (!worst) return result('ok', 'no typed pages');
  return result('ok', graded.map(g => `${g.n} distinct typed values (pack ${g.pool.pack.manifest.name} declares ${g.declared})`).join('; '));
}

/**
 * dangling_aliases (F12): surfaces both slug_aliases redirects and
 * page_aliases free-text names whose target page is gone or soft-deleted.
 * Source-scoped JOINs prevent cross-source false positives.
 *
 * #6619: the two cases are reported apart. Aliases whose target has no page
 * row (purged or hard-deleted) are cleared by `gbrain repair aliases`, named
 * per source; aliases of a soft-deleted page are kept for `gbrain restore`
 * and removed when that page is purged, so nothing is offered for them. The
 * alias tables carry the managed writer guard, so raw SQL is never offered.
 *
 * Defensive: pre-v105 brains don't have slug_aliases yet; a failed read
 * counts nothing (ok).
 */
export async function checkDanglingAliases(
  engine: BrainEngine,
): Promise<OnboardCheckResult> {
  let orphaned: Array<{ source_id: string; slug_redirects: number; page_aliases: number }> = [];
  let soft = { slug_redirects: 0, page_aliases: 0 };
  try {
    orphaned = await engine.executeRaw(ORPHANED_ALIAS_COUNTS_SQL);
    const [row] = await engine.executeRaw<typeof soft>(SOFT_DELETED_ALIAS_COUNT_SQL);
    if (row) soft = row;
  } catch (error) {
    // #7145: only a pre-v105 brain (no alias tables) has nothing to report; any other failure is unknown, not clear.
    if (!isMissingSchemaObject(error, 'table', ['slug_aliases', 'page_aliases'])) {
      return { check: { name: 'dangling_aliases', status: 'warn', details: { health: 'unknown' },
        message: `Dangling aliases unknown: the alias read failed (${redactConnectionInfo(error instanceof Error ? error.message : String(error))}); rerun doctor.` }, remediations: [] };
    }
  }
  const slugAliases = orphaned.reduce((sum, row) => sum + Number(row.slug_redirects), 0) + Number(soft.slug_redirects);
  const pageAliases = orphaned.reduce((sum, row) => sum + Number(row.page_aliases), 0) + Number(soft.page_aliases);
  const n = slugAliases + pageAliases;
  if (n === 0) {
    return {
      check: { name: 'dangling_aliases', status: 'ok', message: 'No dangling aliases' },
      remediations: [],
    };
  }
  const commands = orphaned.map(row => repairPreviewCommand('aliases', { source: row.source_id }));
  const softTotal = Number(soft.slug_redirects) + Number(soft.page_aliases);
  const orphanedText = orphaned.length
    ? `${n - softTotal} point at pages that no longer exist (${orphaned.map(row => `${row.source_id}: ${Number(row.slug_redirects) + Number(row.page_aliases)}`).join(', ')}); `
      + `preview their cleanup with ${commands.join('; ')}, then run the --apply command it prints. `
    : '';
  const softText = softTotal
    ? `${softTotal} belong to soft-deleted pages and are kept for gbrain restore; purging the page removes them, so nothing needs running for those.`
    : '';
  return {
    check: {
      name: 'dangling_aliases',
      status: 'warn',
      message:
        `${n} alias rows point at missing/deleted pages ` +
        `(${slugAliases} slug redirects; ${pageAliases} free-text page aliases). ${orphanedText}${softText}`.trimEnd(),
      details: { orphaned, soft_deleted: soft },
      ...(orphaned.length ? { fix: { argv: commands[0]!.split(' '), consent: [], actor: 'agent' as const, requires_exclusive: false,
        why: 'Lists the orphaned alias rows of that source without changing anything; its output prints the apply command.' } } : {}),
    },
    remediations: [],
  };
}