Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
// src/core/onboard/impact-capture.ts
// sourcescope:file-brain-wide — captureMetric reports brain-wide
// aggregates (orphan_count, stale_count, coverage fractions) by design.
// Per A26 lint opt-out.
//
// v0.41.18.0 (A6 + A25 + A17, T11). Before/after stats for remediation job
// steps, the rows `gbrain onboard --history` reads ("you reduced orphans
// 47% (88% → 41%)"). runRemediation is the writer: it opens a probe before
// it submits a step's job and closes it once that job is terminal. Steps
// whose job moves no tracked metric, dry runs, and steps that throw before
// their job is terminal leave no row.
//
// Every metric is read through the brain's own definition of it, so a row
// agrees with doctor and `onboard --check`: the embed worker's stale-chunk
// count, findOrphanPages under the shared orphan-reporting policy (what
// get_health counts), and the onboard coverage checks' own query.
//
// Best-effort per A17: a stat-query or log-write failure must NOT change the
// step's outcome. Failures log to stderr; a failed capture records null.
//
// Attribution columns per A25 + codex finding #10: rows carry job_id (FK to
// minion_jobs), source_id, started_at and idempotency_key so concurrent
// onboard/autopilot/manual runs can't misattribute deltas to the wrong
// remediation.
import type { BrainEngine } from './../engine.ts';
import type { RemediationStep } from '../remediation-step.ts';
import { loadOrphanPolicyOverrides, shouldExcludeFromOrphanReporting } from '../orphan-policy.ts';
import { LINK_COVERAGE_FEATURE, TIMELINE_COVERAGE_FEATURE, visibleEntityCoverageSql } from './checks.ts';
import { resolveEntityTypes } from '../schema-pack/entity-types.ts';
export type MetricName =
| 'orphan_count'
| 'stale_count'
| 'entity_link_coverage'
| 'timeline_coverage'
| 'takes_count';
export interface ImpactAttribution {
remediation_id: string;
job_id?: number;
source_id?: string;
brain_id?: string;
started_at?: string;
idempotency_key?: string;
applied_by?: string;
}
/** The metric each remediation job moves. A step whose job is not listed writes no row. */
const JOB_METRICS: Readonly<Record<string, MetricName>> = {
embed: 'stale_count',
'embed-catch-up': 'stale_count',
extract: 'orphan_count',
'extract-ner': 'entity_link_coverage',
'extract-timeline-from-meetings': 'timeline_coverage',
'extract-takes-from-pages': 'takes_count',
};
/**
* The tracked metric a remediation job is expected to move, or null when its
* effect has no single metric (its steps then record no history row).
*/
export function impactMetricForJob(job: string): MetricName | null {
switch (job) {
case 'embed':
case 'embed-catch-up':
return 'stale_count';
case 'extract':
return 'orphan_count';
case 'extract-ner':
return 'entity_link_coverage';
case 'extract-timeline-from-meetings':
return 'timeline_coverage';
case 'extract-takes-from-pages':
return 'takes_count';
default:
return null;
}
}
/**
* Pure-ish: returns the current numeric value for `metric`. Returns null
* on any throw (best-effort capture per A17).
*/
export async function captureMetric(
engine: BrainEngine,
metric: MetricName,
): Promise<number | null> {
try {
switch (metric) {
case 'stale_count':
return await engine.countStaleChunks();
case 'orphan_count': {
const [candidates, overrides] = await Promise.all([
engine.findOrphanPages(),
loadOrphanPolicyOverrides(engine),
]);
return candidates.filter((page) => !shouldExcludeFromOrphanReporting(page.slug, overrides, page)).length;
}
case 'entity_link_coverage':
case 'timeline_coverage': {
const feature = metric === 'entity_link_coverage' ? LINK_COVERAGE_FEATURE : TIMELINE_COVERAGE_FEATURE;
const entityTypes = await resolveEntityTypes(engine, null);
if (entityTypes.status === 'pack_unavailable') return null;
const sql = visibleEntityCoverageSql(feature, entityTypes.filter);
const [row] = await engine.executeRaw<{ sample_size: number; matched: number }>(sql.text, sql.params);
const population = Number(row?.sample_size ?? 0);
// An empty population is vacuously covered.
return population === 0 ? 1 : Number(row?.matched ?? 0) / population;
}
case 'takes_count': {
const rows = await engine.executeRaw<{ count: string | number }>(
`SELECT COUNT(*) AS count FROM takes`,
);
return rows.length > 0 ? Number(rows[0].count) : 0;
}
}
} catch (err) {
process.stderr.write(
`[impact-capture] failed to capture ${metric}: ${err instanceof Error ? err.message : String(err)}\n`,
);
return null;
}
}
/**
* Write one migration_impact_log row. Best-effort: a write failure logs
* to stderr but doesn't throw.
*/
export async function writeImpactLogRow(
engine: BrainEngine,
attribution: ImpactAttribution,
metricName: MetricName,
metricBefore: number | null,
metricAfter: number | null,
details?: Record<string, unknown>,
): Promise<void> {
try {
await engine.executeRaw(
`INSERT INTO migration_impact_log (
remediation_id, metric_name, metric_before, metric_after,
job_id, source_id, brain_id, started_at, idempotency_key,
applied_by, details
) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11::text::jsonb)`,
[
attribution.remediation_id,
metricName,
metricBefore,
metricAfter,
attribution.job_id ?? null,
attribution.source_id ?? null,
attribution.brain_id ?? null,
attribution.started_at ?? new Date().toISOString(),
attribution.idempotency_key ?? null,
attribution.applied_by ?? null,
JSON.stringify(details ?? {}),
],
);
} catch (err) {
process.stderr.write(
`[impact-capture] failed to write log row for ${attribution.remediation_id}: ${err instanceof Error ? err.message : String(err)}\n`,
);
}
}
/** A step's metric as read just before its job was submitted. */
export interface StepImpactProbe {
metric: MetricName;
before: number | null;
startedAt: string;
}
type ImpactStep = Pick<RemediationStep, 'id' | 'job' | 'idempotency_key' | 'params'>;
/**
* Read the metric `step`'s job moves, before the job is submitted. Returns
* null (and reads nothing) when the job has no tracked metric.
*/
export async function openStepImpact(engine: BrainEngine, step: ImpactStep): Promise<StepImpactProbe | null> {
const metric = impactMetricForJob(step.job);
if (metric === null) return null;
const startedAt = new Date().toISOString();
return { metric, startedAt, before: await captureMetric(engine, metric) };
}
/**
* Read the metric again now that the step's job is terminal and write the
* step's history row. Never throws: a failed read records null and a failed
* write only logs (A17).
*/
export async function closeStepImpact(
engine: BrainEngine,
probe: StepImpactProbe,
step: ImpactStep,
outcome: { jobId: number; status: string; doctorRunId: string },
): Promise<void> {
const after = await captureMetric(engine, probe.metric);
const sourceId = typeof step.params.sourceId === 'string' ? step.params.sourceId : undefined;
await writeImpactLogRow(
engine,
{
remediation_id: step.id,
job_id: outcome.jobId,
started_at: probe.startedAt,
idempotency_key: step.idempotency_key,
source_id: sourceId,
},
probe.metric,
probe.before,
after,
{ job: step.job, status: outcome.status, doctor_run_id: outcome.doctorRunId },
);
}