Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
// v0.39 T4 — gbrain schema review-candidates + T5 review-orphans.
//
// Per D3(eng) + codex finding #10: review-candidates re-derives candidate
// names from disk on demand instead of reading the privacy-redacted
// candidate-audit JSONL. Preserves the SHA-8 type-name redaction contract
// for the audit (therapy/adversary/hater-dossier categories) while still
// giving the CLI human-readable type names.
//
// The CLI surface (src/commands/schema.ts:runReviewCandidatesCmd) makes
// this EXPLICIT: every output starts with "Disk-derived candidates from
// current brain state" so users understand what they're reviewing.
import type { BrainEngine } from '../engine.ts';
import { runDetect } from './detect.ts';
import { loadActivePack } from './load-active.ts';
import { loadActivePackForLocalEngine } from './best-effort.ts';
import { storedTypeMissesPack, type TypeUsagePack } from './type-usage.ts';
import { loadConfig, gbrainPath, configPath } from '../config.ts';
import { existsSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
import { dirname } from 'node:path';
export interface ReviewCandidatesOpts {
sourceId?: string;
/** When set, promote this prefix to the active pack as a new page_type. */
applySlug?: string;
}
export interface CandidateReview {
prefix: string;
page_count: number;
suggested_type: string;
in_active_pack: boolean;
}
export interface ReviewCandidatesResult {
candidates: CandidateReview[];
applied: string | null;
source_id: string;
}
export async function runReviewCandidates(
engine: BrainEngine,
opts: ReviewCandidatesOpts = {},
): Promise<ReviewCandidatesResult> {
const sourceId = opts.sourceId ?? 'default';
const detected = await runDetect(engine, { sourceId });
const cfg = loadConfig();
let activeTypeNames = new Set<string>();
let activePackName = 'gbrain-base';
try {
const pack = await loadActivePack({ cfg, remote: false, sourceId });
activePackName = pack.manifest.name;
activeTypeNames = new Set(pack.manifest.page_types.map((t) => t.name));
} catch {
// Active pack load failure: fall through with empty active set.
}
const candidates: CandidateReview[] = detected.prefixes
.filter((p) => !activeTypeNames.has(p.suggested_type))
.map((p) => ({
prefix: p.prefix,
page_count: p.page_count,
suggested_type: p.suggested_type,
in_active_pack: false,
}));
let applied: string | null = null;
if (opts.applySlug) {
const match = candidates.find((c) => c.prefix === opts.applySlug || c.suggested_type === opts.applySlug);
if (!match) {
throw new Error(`--apply target not found in current candidate set: ${opts.applySlug}`);
}
// Append the new type to a USER pack derived from the active pack.
// For v0.39.0.0 the simplest correct path is: write a delta file under
// ~/.gbrain/schema-pack-deltas/<active>-<timestamp>.json so users can
// review + merge into their pack via `gbrain schema edit`.
const deltaDir = gbrainPath('schema-pack-deltas');
mkdirSync(deltaDir, { recursive: true });
const ts = new Date().toISOString().replace(/[:.]/g, '-');
const deltaPath = `${deltaDir}/${activePackName}-${ts}.json`;
writeFileSync(deltaPath, JSON.stringify({
schema_version: 1,
active_pack: activePackName,
added_at: new Date().toISOString(),
delta: {
page_types: [{
name: match.suggested_type,
primitive: 'entity',
path_prefixes: [match.prefix],
aliases: [],
extractable: false,
expert_routing: false,
}],
},
source_id: sourceId,
}, null, 2));
applied = deltaPath;
}
return { candidates, applied, source_id: sourceId };
}
// ----- T5 review-orphans ------------------------------------------
export interface TypeOrphan {
slug: string;
source_id: string;
/** Stored `pages.type` ('' when untyped). */
type: string;
reason: 'untyped' | 'undeclared';
}
export interface TypeOrphansResult {
/** Every page in scope with no active-pack type match (not just the returned page). */
orphan_count: number;
orphans: TypeOrphan[];
/** Stored types the pack neither declares nor aliases, with page counts. */
undeclared_types: Array<{ type: string; count: number }>;
/** Active pack name, or null when no pack resolved (only untyped pages are then checked). */
pack: string | null;
/** True when orphan_count exceeds the returned orphans. */
truncated: boolean;
}
/**
* Pages with no active-pack type match: an empty type, or a type the pack
* neither declares nor aliases (`storedTypeMissesPack`, the same predicate as
* `schema lint --with-db`'s `stored_type_undeclared`). Shared by the
* `schema review-orphans` CLI and the `schema_review_orphans` MCP op.
*/
export async function findTypeOrphans(
engine: BrainEngine,
manifest: (TypeUsagePack & { name: string }) | null,
scope: { sourceId?: string; sourceIds?: string[] },
limit: number,
): Promise<TypeOrphansResult> {
const params: unknown[] = [];
let where = 'deleted_at IS NULL';
if (scope.sourceIds && scope.sourceIds.length > 0) {
params.push(scope.sourceIds);
where += ` AND source_id = ANY($${params.length}::text[])`;
} else if (scope.sourceId) {
params.push(scope.sourceId);
where += ` AND source_id = $${params.length}`;
}
const typeRows = await engine.executeRaw<{ type: string | null; n: string }>(
`SELECT type, count(*)::text AS n FROM pages WHERE ${where} GROUP BY type`,
params,
);
const missing = typeRows.filter((r) => (manifest ? storedTypeMissesPack(r.type, manifest) : !r.type));
const undeclared = missing
.filter((r): r is { type: string; n: string } => !!r.type)
.map((r) => ({ type: r.type, count: Number(r.n) }))
.sort((a, b) => b.count - a.count || a.type.localeCompare(b.type));
const orphanCount = missing.reduce((sum, r) => sum + Number(r.n), 0);
if (orphanCount === 0) {
return { orphan_count: 0, orphans: [], undeclared_types: [], pack: manifest?.name ?? null, truncated: false };
}
const rowLimit = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 100;
const rows = await engine.executeRaw<{ slug: string; source_id: string; type: string | null }>(
`SELECT slug, COALESCE(source_id, 'default') AS source_id, type FROM pages
WHERE ${where} AND (type IS NULL OR type = '' OR type = ANY($${params.length + 1}::text[]))
ORDER BY source_id, slug
LIMIT ${rowLimit}`,
[...params, undeclared.map((u) => u.type)],
);
return {
orphan_count: orphanCount,
orphans: rows.map((r) => ({
slug: r.slug,
source_id: r.source_id,
type: r.type ?? '',
reason: r.type ? 'undeclared' : 'untyped',
})),
undeclared_types: undeclared,
pack: manifest?.name ?? null,
truncated: orphanCount > rows.length,
};
}
export interface ReviewOrphansOpts {
sourceId?: string;
}
export interface ReviewOrphansResult extends TypeOrphansResult {
source_id: string;
}
export async function runReviewOrphans(
engine: BrainEngine,
opts: ReviewOrphansOpts = {},
): Promise<ReviewOrphansResult> {
const sourceId = opts.sourceId ?? 'default';
const pack = await loadActivePackForLocalEngine(engine, { sourceId });
const result = await findTypeOrphans(engine, pack?.manifest ?? null, { sourceId }, 1000);
return { ...result, source_id: sourceId };
}