Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
46.7 KB
Raw Blame

Key files: Commands (3/6)

Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.

  • src/commands/engine-status.ts — gbrain engine status [--json] [--probe] [--brain <id>]: the ENGINE-FREE detection primitive (CLI_ONLY, dispatched in handleCliOnly BEFORE connectEngine like pglite-repair; deliberately NOT an operations.ts op — an MCP server can't serve a status call when its DB is down). Zero round-trips without --probe: reports (JSON schema_version: 1) effective_engine vs config_file_engine (can differ under a transient env URL), db_url_source, env-shadow + both-env-URLs precedence note, redacted URLs only, brain id from the engine-free resolver (NOT get_brain_identity, which needs an engine), thin-client flag, and a Postgres pooler block (supabase-pooler detection, resolvePrepare, direct/session-pooler derivability, GBRAIN_DISABLE_DIRECT_POOL, pool sizes). --brain <id>/mount resolution reports the MOUNT's engine/URL, never the host's. --probe is a SINGLE bounded connect + SELECT 1 (the driver's built-in connect_timeout — never a custom race; noRetry, never the 3-attempt ladder); Postgres success also reports ConnectionManager.describeMode(); failure returns a classified PgAccessDiagnosis. PGLite probe is LOCK-AWARE: a live serve holding the single-writer data-dir lock reports locked_by_serve (healthy-with-note) instead of hanging ~30s and misreporting a healthy brain. Exit 0 healthy, 1 on config diagnosis or failed probe, 2 on flag errors. Pinned by test/engine-status.test.ts.

  • src/commands/enrich.ts + src/core/enrich/thin.ts + src/core/cycle/enrich-thin.ts — gbrain enrich --thin: batch-develops stub (thin) pages via brain-internal grounded synthesis. gbrain's model tooling sees only brain-internal context (search / get_page / facts / backlinks), not the web, so enrich consolidates what the brain ALREADY knows about an entity (scattered across meetings, other pages, deals, facts) into one cited page via ONE gateway.chat call per page; web research stays the agent-driven enrich SKILL's job. runEnrichCore(engine, opts, signal) refuses managed mutation before provider work until its resume cursor can retain prepared writes (dry-run remains available); legacy writes expose pending/failed request IDs. It is strict per-source (multi-source iteration is the caller's job) and drives enrichOne per candidate: withRefreshingLock('enrich:<src>:<slug>') → coherent readPageSnapshot (content, tags, revision) → deterministic retrieve (hybridSearch + getBacklinks + facts + raw_data, source-scoped, sanitized via INJECTION_PATTERNS) → assessGrounding gate (skip < MIN_CONTEXT_CHARS, no LLM) → buildEnrichPrompt (grounded dossier, [Source: slug] citations, SKIP sentinel) → synth → put_page handler (remote:false, observed revision and caller-allocated request UUID, atomic projections and receipt) stamping enriched_at + enriched_by:'cli:enrich'. Candidate selection is the SQL-native engine.listEnrichCandidates(opts) (src/core/engine.ts interface + EnrichCandidate/EnrichCandidatesOpts/ENRICH_ORDER_SQL in src/core/types.ts + pg/pglite impls): thin-filter + per-page source-correct inbound count (to_page_id = p.id, mentions and non-ranking link types excluded) + enriched_at recency guard + whitelisted ORDER BY + LIMIT, lightweight projection (NO bodies). Resume via src/core/op-checkpoint.ts (local enrichFingerprint); budget via BudgetTracker + withBudgetTracker (best-effort under --workers > 1 — runSlidingPool aborts new claims on BUDGET_EXHAUSTED but does NOT cancel in-flight gateway.chat; pin --workers 1 for a hard ceiling). sanitizeContext (thin.ts) neutralizes the <context>…</context> data-envelope delimiters (injection escape, mirrors the </trajectory> convention); --background asks consent first and stores a spend group; the --background multi-source fan-out idempotency key carries the run fingerprint via exported backgroundIdempotencyKey(sid, args) (a bare enrich:${sid} would return stale completed jobs); runEnrichCore flags budget_exhausted post-hoc when tracker.totalSpent > tracker.cap even when the gateway swallowed the final-call throw (via read-only BudgetTracker.cap getter); body() flushes the checkpoint on BudgetExhausted before it propagates so resume doesn't re-charge. The opt-in enrich_thin cycle phase (default OFF via cycle.enrich_thin.enabled) trickles max_pages_per_tick (default 3) per source with per-source cost cap enforced as min(per_source_cap, brain_wide_remaining) + brain-wide total + walltime caps. Wired into cycle.ts (CyclePhase/ALL_PHASES between conversation_facts_backfill and skillopt/embed; PHASE_SCOPE='source'; NEEDS_LOCK; dispatch), cli.ts (CLI_ONLY + CLI_ONLY_SELF_HELP + THIN_CLIENT_REFUSED_COMMANDS + dispatch), jobs.ts (Minion enrich handler, strict per-source, NOT in PROTECTED_JOB_NAMES). DI seam opts.synthesizeFn keeps tests hermetic (no API key, no mock.module). Pinned by test/enrich/thin.test.ts, test/enrich/idempotency.test.ts, test/enrich-cycle-phase.test.ts, test/e2e/enrich-pglite.test.ts (grew-cited, skip, ordering, multi-source, recency, resume, budget abort + checkpoint flush, final-call overage, lock-skip, provenance), test/e2e/engine-parity.test.ts (listEnrichCandidates pg↔pglite parity).

  • src/commands/eval-compare.ts — gbrain eval compare [--suite S] [--modes ...] [--runs ...] [--baseline RUN_ID --candidate RUN_ID] [--draws N] [--seed N] [--md|--json] [--input PATH]. Reads the run ledger <repo>/.gbrain-evals/eval-results.jsonl, keeps the newest record per (suite, mode) and renders the mode table plus any aggregate metrics. Paired statistics come only from per-query rows: a record whose params.output names its per-question JSONL (gbrain eval longmemeval --record --output) is joined with its pair on question_id, and each per-query metric both rows carry (recall_all@k, recall_any@k, qa_accuracy from judge_correct) gets a paired cluster bootstrap 95% CI, a two-sided sign-flip p-value and a Holm p-value across the report's comparisons (src/core/eval/paired-bootstrap.ts). Pairs are every mode pair in a suite, or exactly --baseline/--candidate. Significant means Holm p ≤ 0.05 and a CI that excludes 0. A params.output path must resolve inside the repository root after following symlinks (pathWithinRoot); a .., absolute or symlinked path outside it is refused and never read. Runs without rows are listed in paired_unavailable, and a report with no comparisons says it is aggregate-only; _meta.methodology describes only what was computed. Pinned by test/eval-compare.test.ts.

  • src/commands/eval-cross-modal.ts — multi-model quality gate. Three different-provider models score the OUTPUT against the TASK on 5 dims. Verdict pass (exit 0) / fail (exit 1) / inconclusive (exit 2; <2/3 model successes). Reuses gateway chat() (recipe-registry auth/aliasing, no parallel provider stack). Self-configures the gateway from loadConfig() + env (cli.ts skips connectEngine()); opts.useConfiguredGateway (the nightly probe) keeps the caller's brain-resolved gateway instead. Unkeyed slot defaults take the chat model (substituteUnavailableDefaultSlots, #4636; --slot-*-model wins). Default cycles 3 in TTY, 1 in non-TTY via resolveCycleDefault (src/core/eval/cycle-default.ts); the cost banner appends cycleDefaultSuffix(...) on that silent fallback. Receipts: gbrainPath('eval-receipts')/<slug>-<sha8>.json. --batch <jsonl> [--limit N] [--max-usd F] [--yes] scores a LongMemEval-shape JSONL; exclusive with --task (usage error); filters kind: "by_type_summary" rows; pre-flight estimate refuses over --max-usd (default 5) without --yes. Shared runWithLimit fan-out: --concurrent N questions × 3 slots (default 3 → 9 calls). Per-question receipts live in a tempdir deleted at run end; the summary inlines per-question verdicts, slot-indexed slot_scores and the judge panel (distinct models/providers of the slots that scored, per-slot slot_scored_questions); stderr names a shared model, a silent slot and a panel under 3 providers, verdict unchanged (the nightly probe, not the batch, turns a collapsed panel inconclusive). Batch exit precedence (not aggregate.ts's): ERROR > FAIL > INCONCLUSIVE > PASS. DI seam: opts.runEval (like LongMemEval's client) bypasses real LLM calls and, without useConfiguredGateway, the gateway availability check. Pinned by test/eval-cross-modal-batch.test.ts.

  • src/commands/eval-export.ts — streams eval_candidates rows as NDJSON to stdout with schema_version: 1 prefix on every line. EPIPE-safe, progress heartbeats on stderr, stable id-desc tiebreaker so --since windows never dupe/miss rows. D2: eval declares jsonSubcommands {export, replay, gate: 'ndjson'}; under --json each row is a writeNdjsonLine and argv errors are one {status:'error'} envelope line (invalid_params, exit 2).

  • src/commands/eval-longmemeval.ts + src/eval/longmemeval/{harness,adapter,sanitize,extract,intent,reader,emit,capture,gateway-client,trajectory-route,decide-lane}.ts — gbrain eval longmemeval <dataset.jsonl> runs the public LongMemEval benchmark against gbrain's hybrid retrieval and is the repo's receipt producer for the strict retrieval metric and, with --judge, for judged answer accuracy (both reproduction paths are in docs/eval-bench.md). One in-memory PGLite per run via createBenchmarkBrain + withBenchmarkBrain; between questions, TRUNCATE over runtime-enumerated pg_tables with the infrastructure tables (sources, config, gbrain_cycle_locks, subagent_rate_leases, and decide_calibrations for System One arms) preserved — which is why the run's pins, written once via engine.setConfig, hold for every question. cli.ts pre-dispatch bypass skips connectEngine(), so ~/.gbrain is never opened. Embedded callers use RunOpts.exitOnError: false to throw rather than terminate the host and preflight resolved chat providers before embedding; standalone CLI exits remain unchanged. Metric (metrics.ts): recall joins on RAW dataset session ids through a per-question slug→raw map; recall_all@k (every gold session among the distinct sessions of the top-k CHUNK rows returned at limit: k) is the headline, recall_any@k the diagnostic, and the per-row recall_hit is a deprecated alias of recall_any_hit; _abs abstention questions are emitted with abstention: true but stay out of the recall denominators unless --include-abstention; a slug collision touching a gold id aborts that question with an error row. Pins: --mode, --reranker on|off, --autocut on|off, --expansion (OFF for every mode — the per-call setting wins over the bundle, so --mode tokenmax alone never expands), --expansion-variant-budget legacy|(0,4], --search-pin KEY=VALUE (repeatable; any search.* key, written verbatim via engine.setConfig); precedence is explicit flag > --search-pin > injected RunOpts.searchConfigSnapshot > bundle, so a flag wins over a pin on the same key. The raw --search-pin map folds into retrieval_config_hash (only when non-empty, so pin-free runs keep their hash identity) while the knobs hash covers only the resolved mode knobs. The reranker gate keys on the RESOLVED pin (flag, --search-pin, snapshot or bundle), not only on an explicit --reranker on: a run that resolves to reranker on preflights rerankerReadinessForEngine and exits 2 with the fix when the reranker cannot run (a balanced run with no VOYAGE_API_KEY exits with the fix text — --reranker off or set the key — instead of quietly scoring un-reranked rows). Gates (exit 1): a run in which every question errored, a row that fell through un-reranked under a resolved reranker-on pin (reranker_skipped_rows), a row whose vector arm silently degraded to keyword-only on a non---keyword-only run (vector_degraded_rows: vector_enabled:false / embed_unavailable / embed_timeout), an --expansion row that did not expand as configured (expansion_failed_rows), an --expansion-replay miss, and --by-type-floor F breaches — which gate on recall_all by default (--by-type-floor-metric recall_any selects the lenient rate). The run-end gates and GBRAIN_LME_DEBUG=1 prints per-question wall time to stderr; --record run through ONE finishRun from both the main path and the no-op resume path. Rows: retrieved[] (every returned chunk row: slug, chunk_id, RAW session_id, rank, score, rerank_score?, alias_hit?), retrieved_session_ids, distinct_sessions_in_top_k, gold_total/gold_found, search_meta (vector_enabled, expansion_applied, degraded, derived reranked = some finite rerank_score and no skip stage, autocut), retrieval_config_hash, the reader pins on every answered row (reader_model = the requested id, reader_model_snapshot = the provider-reported id when it differs — a dated API snapshot — else null, reader_prompt_sha, reader_max_tokens; --retrieval-only rows carry retrieval_only: true instead so a judge backfill can refuse them), expansion_variants when expansion ran (--expansion-replay FILE serves them back and stamps expansion_replayed, so every cell differs only in its knobs), and with --capture-pool a rerank_pool — the exact pre-autocut returnPool hybridSearch hands to applyAutocut (via HybridSearchOpts.onRerankPool; unscored alias/exact-lookup injections included; rrf_rank, pool_rank, est_tokens per row; autocut_kept_keys when the returned rows are the kept set) for the offline autocut-floor replay. Summary: --by-type emits a schema_version: 2 by_type_summary (per-type + aggregate {total, all_hit, all_rate, any_hit, any_rate}, excluded_abstention, mean_distinct_sessions, legacy_rows, gold_missing_from_haystack, slug_collisions, and run_config: every pin, embedder model@dims, dataset sha256 + question count, knobs_hash + KNOBS_HASH_VERSION, retrieval_config_hash, the embed-cache receipt, the degradation counters); resume-replace keeps exactly ONE summary at the tail (emit.ts:emitByTypeSummary: the summary is always the FINAL line — any prior by_type_summary is removed before the new one is appended, and the file rewrite is atomic, <path>.summary.tmp + rename, so a kill mid-write never truncates the paid rows — its _meta.metric_glossary is the ONE glossary block per response and names exactly the metrics carried, recall_all@k, recall_any@k, and qa_accuracy when the judge lane ran; a CR inside any emitted line throws rather than splitting a JSONL record). Reader (reader.ts): the selected reader system text is constant across questions — every per-question input (question, Current Date: {question_date} when the dataset row carries one, the trajectory block, the sanitized <chat_session> blocks) lives in the USER message — so reader_prompt_sha (sha256 of the selected system text) is a run-level pin, alongside mode, version, model and output budget. Notes-first/1024 is the reader default; direct/512 retains the original prompt (official cap 500). Disclosed deviations from the official run_generation.py prompt: an abstention instruction (say the information is not available / "I don't know" when the retrieved sessions lack it — without it the 30 _abs questions are answered and judged wrong by construction), the #4338 data-boundary framing + pattern stripping, and the configurable cap. resolveReaderConfig, buildReaderRequest and readerConfigHash are available through gbrain/eval/longmemeval/reader to companion evals; generateAnswer returns {text, response_model, finish_reason}, response_model being the provider-reported snapshot when it differs from the requested id (the harness's gateway client maps ChatResult.responseModel ?? model into the Anthropic-shaped message.model). Judge lane (--judge): implies --by-type; --judge --retrieval-only is a usage error. Preflight (judge-lane.ts:judgePreflight): no usable chat provider for the judge model → exit 1; --max-usd against an unpriced model → exit 2 (pass --max-usd off); estimate over the cap without --yes → exit 2. The estimate (judge.ts:estimateJudgeRunUsd) assumes the selected reader output cap per live hypothesis and the stored hypothesis for backfill rows; the BudgetLedger soft-stops at the cap and the remaining rows are stamped judge_skipped: 'budget'. Live rows are judged inline after each reader call. --judge --resume-from FILE is the judge-only backfill: selectBackfillRows picks every prior row with a hypothesis and no settled verdict (judge_error rows are re-judged, --retrieval-only rows are refused, rows absent from the dataset are left unjudged with a WARN); a same-file resume ALWAYS appends (makeEmitter(outputPath, append) has no atomic-rewrite mode — appending is the only write path) — judged backfill rows and retries land as newer duplicates the moment they finish, so a timeout or kill loses at most the in-flight question — and compactJsonlByQuestionId (emit.ts) rewrites the file atomically (<path>.compact.tmp + rename) to one row per question_id (last wins, first-seen order) before the summary is emitted; readJsonlRows / loadResumeSet read appended files last-wins and --judge-concurrency N parallelizes the backfill. Every judged row carries judge_config_hash — the judge pins (model, JUDGE_PROMPT_VERSION, max_tokens, temperature) plus the reader pins the row was produced under; a prior row hashes from its OWN recorded reader_model / reader_prompt_sha / reader_max_tokens, so a file answered by another reader is never relabelled as this run's, and rows already judged under a different hash are refused unless --allow-mixed-run-config. Run end: qa_accuracy (qa-accuracy.ts) is rebuilt from ALL rows (prior + new, last row per question_id wins) whenever the lane ran or any row carries a verdict; a run with judge_errors > 0, skipped_budget > 0 or unjudged > 0 (the qa_accuracy.complete predicate) prints a FAIL … NOT publishable line and exits 1 unless --allow-incomplete-judgments (WARN, exit 0) — the fix is --judge --resume-from FILE until all three are 0; a row whose judge call threw is stamped judge_error: 'provider_error' by the backfill, never silently left unjudged. Judge row fields: exactly one of judge_correct / judge_error (+ secret-redacted judge_error_detail) / judge_skipped, plus judge_model, judge_model_snapshot, judge_raw (first 200 chars), judge_cost_usd, judge_attempts, judge_prompt_kind, judge_prompt_version, judge_config_hash. RunOpts.judgeClient / judgeBackoffMs are the test seams. Embed cache: on by default at ~/.cache/gbrain-eval/longmemeval-embed.sqlite (--embed-cache FILE / --no-embed-cache; never installed on --keyword-only), installed through the gateway embed-transport seam so every arm sees byte-identical vectors; the cache transaction wraps only the embed-producing section of a question (import + search), never a reader call. Resume: --resume-from FILE re-scores prior rows from retrieved[] + the dataset's gold (stored booleans are never trusted), refuses reader-mode/prompt/model/budget changes unconditionally (historical direct rows require --reader-mode direct), and refuses a different retrieval_config_hash unless --allow-mixed-run-config; error rows without a hypothesis are retried. --question-ids FILE restricts the run to a listed slice (unknown ids or an empty file exit 1); --record appends a secret-redacted EvalRunRecord (schema 3, suite longmemeval, params = run_config) via persistRunRecord. Flags live in ONE table, LME_FLAGS, that drives both parseArgs and printHelp, so the flag-registry scan sees every literal and help cannot drift from the parser; a switch written with a value (--judge=true) exits 1 like an unknown flag. Sanitization parity: harness.ts reuses INJECTION_PATTERNS from src/core/think/sanitize.ts; retrieved chat content is wrapped in <chat_session id="..." date="..."> and the answer-gen system prompt declares it UNTRUSTED. RunOpts seams — client, extractorClient/extractorModel, engine, searchConfigSnapshot, expandFn, embedTransport, rerankerReadiness, recordDir — let the full pipeline run hermetically without an API key. Trajectory routing (default on; --no-trajectory bypasses BOTH the extractor and the intent routing, the like-for-like retrieval setting): extract.ts runs the claim extractor (RunOpts.extractorModel, else the utility tier) over each haystack session into the benchmark brain's facts table (content-hash cache, per-question alias map, fail-open on every error path), intent.ts prefers the dataset's question_type before the SHARED regex set from src/core/think/intent.ts, temporal/knowledge_update questions splice a findTrajectory block into the reader prompt, and rows carry intent, trajectory_points, entity_resolved, resolution_source, methodology_note (trajectoryMethodologyNote: extractor=haiku-preprocess-full-haystack-v1 for a Haiku extractor, else extractor=<model id>-preprocess-full-haystack-v1 — "gbrain + extractor-preprocess", not "gbrain alone"). Incomplete reader output (max_tokens, empty or unknown finish) records its partial text only in reader_partial_output, clears the hypothesis, counts as a failed question and cannot be judged; reader_finish_reason is stamped on answered attempts. Pinned by test/eval-longmemeval-reader-mode.slow.test.ts, test/longmemeval-reader.test.ts, test/longmemeval-metrics.test.ts, test/eval-longmemeval-mixedcase.slow.test.ts (raw-id join, strict/any split, abstention, pins, gates over the placeholder fixture test/fixtures/longmemeval-mixedcase.jsonl), test/eval-longmemeval-cli-smoke.test.ts, test/longmemeval-embed-cache.test.ts, test/longmemeval-judge.test.ts + test/eval-longmemeval-judge.slow.test.ts (the judge lane, reader pins and qa_accuracy denominators), test/eval-longmemeval.slow.test.ts, test/eval-longmemeval-e2e.slow.test.ts, test/eval-longmemeval-search-config.test.ts, test/longmemeval-extract.test.ts, test/longmemeval-intent.test.ts, test/longmemeval-trajectory-routing.test.ts. System One arms (decide-lane.ts, shared flags in src/eval/decide-eval-flags.ts): --decide <slot>=<mode> and the --decide-* flags configure each benchmark brain so the slot acts, fold run_config.decide into retrieval_config_hash, stamp a per-row decide receipt and run_config.decide_summary, restrict to the --decide-dataset eval half, refuse trajectory routing (it reads question_type), and with --decide answerable=on let the S4 verdict abstain replace the reader call; --eval-pool-depth N (eval-only, src/core/search/eval-pool-depth.ts) lifts the per-arm cap to N and pins top_n_in; --capture-pool rows carry pool_recall at fused depths 30/50/100/300 (capture.ts). All-off rows are unchanged. Tests: test/eval-longmemeval-decide.serial.test.ts, test/eval-pool-depth.test.ts.

  • src/commands/eval-prune.ts — explicit retention cleanup. Requires --older-than DUR. --dry-run reports would-delete count.

  • src/commands/eval-replay.ts — contributor-facing replay tool. Reads NDJSON from gbrain eval export, re-runs each captured query / search op against the current brain, computes set-Jaccard@k between captured + current retrieved_slugs, top-1 stability rate, and latency Δ. Stable JSON shape (schema_version: 1) for CI gating; human mode prints a regression table. Pure Bun, zero new deps. The dev-loop half of BrainBench-Real. See docs/eval-bench.md. parseNdjson skips lines where _kind === 'baseline_metadata' so gbrain bench publish baselines parse cleanly without the metadata header polluting row counts. Exports replayCore(engine, opts): Promise<{summary, results}> + ReplaySummary type so gbrain eval gate calls replay in-process (NOT subprocess — avoids gbrain-version-drift for source-tree CI). CLI runEvalReplay wraps replayCore. D2: under the --json guard the result is one compact NDJSON line (writeJsonLine; unguarded callers keep the pretty document) and failures end with a {status:'error'} envelope line (invalid_params exit 2, not_found, parse_error). eval gate follows the same contract; a breached gate is the result line then a gate_failed error line (exit 1).

  • src/commands/eval-suspected-contradictions.ts + src/core/eval-contradictions/{judge,runner,types,date-filter,cost-tracker,cache,severity-classify,cross-source,trends,calibration,judge-errors,auto-supersession,scoped-read}.ts — gbrain eval suspected-contradictions [run|trend|review]. Probe samples top-K retrieval pairs per query (cross-slug + intra-page chunk-vs-take), date pre-filters (3-rule layered — same-paragraph-dual-date overrides separation rule), LLM judge (query-conditioned; UTF-8-safe truncation; confidence-floor double-enforcement; resolution_kind output drives paste-ready commands), persistent cache keyed on (chunk_a_hash, chunk_b_hash, model_id, prompt_version, truncation_policy) (prompt edits cleanly invalidate prior verdicts), Wilson 95% CI calibration on the headline percentage with small_sample_note when n<30, judge_errors as first-class typed counters (parse_fail/refusal/timeout/http_5xx/unknown — avoids bias from silent skip), trend writes to eval_contradictions_runs, source-tier breakdown reuses DEFAULT_SOURCE_BOOSTS prefix logic, deterministic sampling (combined_score DESC + lex tiebreaker for stable cache hit-rate). Hermetic via judgeFn + searchFn DI in the runner; never touches the real gateway in tests. Engine surface: BrainEngine.listActiveTakesForPages (batched), writeContradictionsRun + loadContradictionsTrend, getContradictionCacheEntry + putContradictionCacheEntry + sweepContradictionCache. Schema migrations v51 + v52. Pair members carry only content effective dates; a fallback date becomes null ((date unknown)). MCP op find_contradictions (read scope, NOT localOnly, NOT in subagent allowlist — user-initiated only; the stored report as written answers only trusted local callers without a user-selected source or trust floor, keyed on ctx.localSourceImplicit from makeContext; every other caller goes through scoped-read.ts resolveScopedFindings, which re-reads each side by chunk or take id under pageReadFilter(live), current text projection, safe chunks, holder allow-list and floor, drops a finding unless both sides are visible and unchanged, rebuilds the resolution command from live rows and withholds a supersede of a higher-trust take). Doctor check surfaces high-severity findings with paste-ready resolution commands; synthesize phase pre-fetches the latest probe's top-5-by-severity findings and threads them into buildSynthesisPrompt as an informational block. Architecture doc: docs/contradictions.md.

  • src/commands/eval-trajectory.ts + src/commands/founder-scorecard.ts + src/core/trajectory.ts — temporal trajectory + founder scorecard. gbrain eval trajectory <entity> shows the chronological typed-claim history (mrr/arr/team_size/etc) with regressions auto-flagged inline; gbrain founder scorecard <entity> rolls up claim_accuracy / consistency / growth_trajectory / red_flags into one JSON. Pure-function math in trajectory.ts: detectRegressions(points, threshold) walks consecutive comparable pairs from comparablePairs (same metric, unit and period, strictly later valid_from; values that disagree at one valid_from break the chain) (10% drop default, env override GBRAIN_TRAJECTORY_REGRESSION_THRESHOLD); computeDriftScore(points) returns 1 - mean(cosine(emb[i], emb[i-1])) over existing embeddings (null when <3 embedded points). Backed by BrainEngine.findTrajectory(opts) — both Postgres and PGLite, single SQL query that selects the NEWEST limit points (ORDER BY valid_from DESC, id DESC) and returns them chronologically, so a capped series keeps its latest value. Source-scoped via the sourceId scalar / sourceIds array dual pattern; visibility-filtered for remote callers. MCP op find_trajectory (read scope, NOT localOnly) registered after find_experts. Migration v67 adds optional typed-claim columns (claim_metric, claim_value, claim_unit, claim_period) + a partial index on (entity_slug, claim_metric, valid_from) WHERE claim_metric IS NOT NULL. Fence widens from 10 to 14 cells when any row has typed data; renderer stays at 10 cells when none do (no churn diff on existing fences). Metric labels normalize to lowercase snake_case via normalizeMetricLabel (15-entry seed map). The consolidate cycle phase does semantic upsert keyed on (page_id, claim, since_date) (so re-running the cycle after extract_facts clears consolidated_at cannot append duplicates via MAX(row_num)+1) and writes chronological valid_until on each cluster's older facts. The extract_facts cycle phase batch-embeds via gateway.embed() before insert AND threads pages.effective_date as the pageEffectiveDate fallback for valid_from (precedence: fence-row > pageEffectiveDate > now()). The contradiction probe MUST NOT write valid_until — grep guard at test/eval-contradictions/no-valid-until-write.test.ts. Haiku extraction lives in src/core/facts/extract.ts (not the extract-facts.ts cycle phase); its output cap is config facts.extraction_max_tokens (default 4000), a stopReason: 'length' response retries once at 2× the cap, and persistent truncation warns loudly on stderr instead of silently extracting zero facts. Mixed extractor arrays salvage valid candidates and warn with the dropped malformed count; all-malformed output still fails retryably, while an explicitly empty facts array remains a successful empty result. pageEffectiveDate is OPTIONAL because fence-write.ts callers have no Page object. Migration v89 adds a nullable event_type TEXT column on facts so the substrate carries event-shaped rows (event_type='meeting' / 'job_change' / 'location_change') alongside metric rows. TrajectoryPoint.event_type: string | null projected by both engines. TrajectoryOpts.kind?: 'metric' | 'event' | 'all' filter (default 'all'); founder-scorecard + eval-trajectory pass kind: 'metric' explicitly. Back-compat pinned by test/regressions/v0_40_2_0-trajectory-backcompat.test.ts (byte-identical computeFounderScorecard + computeTrajectoryStats with and without event rows); engine parity in test/engine-parity-event-type.test.ts.

  • src/commands/eval-whoknows.ts — gbrain eval whoknows <fixture.jsonl> [--json] [--skip-replay]: two-layer eval gate. Layer 1 quality (hand-labeled fixture, top-3 hit rate ≥ 0.8). Layer 2 regression (eval_candidates replay set-Jaccard@3 ≥ 0.4). Sparseness fallback: < 20 replay-eligible rows → Layer 2 auto-skips with stderr warning. Stable JSON envelope with schema_version: 1; exit 0/1/2 for pass/fail/usage. WhoknowsFn callable abstraction makes the gates impl-agnostic; runEvalWhoknows(engine: BrainEngine | null, args) picks the impl at entry — thin-client mode (isThinClient(cfg)) routes per-query through callRemoteTool(cfg, 'find_experts', {topic, limit}), local mode calls findExperts(engine, ...) directly. cli.ts adds a thin-client bypass before connectEngine (dispatch shape under src/commands/eval.ts); the regression gate auto-skips in thin-client mode (no DB access to eval_candidates). Public exports jaccardAtK, topKHit, readFixture, WhoknowsFn, threshold constants pinned by test/eval-whoknows.test.ts (25 cases incl. null-engine signature contract).

  • src/commands/eval.ts — gbrain eval command: single-run table + A/B config comparison. Sub-subcommand dispatch on args[0] routes gbrain eval export + gbrain eval prune + gbrain eval replay into session-capture handlers; bare gbrain eval --qrels … fall-through preserves the legacy IR-metrics flow. gbrain eval cross-modal is in the dispatch (the user-facing path is the cli.ts no-DB branch — src/commands/eval.ts:cross-modal only fires when callers re-enter with an existing engine).

  • src/commands/export.ts + src/core/export-snapshot.ts + src/core/export-stage.ts + src/core/export-publish.ts — local Markdown export collects source/page/canonical-withdrawal/tag/raw state in one export-scoped repeatable-read read-only transaction, using 256-key ID batches and private disk-backed SQLite staging. Primary-key page reads reuse the canonical withdrawal overlay without source-wide slug scans under stale planner statistics. Each 256-key batch groups by source and retains only one capacity-checked withdrawal ledger at a time; bodies with no literal gbrain:facts: marker skip normalization, while malformed/orphan markers still use canonical SQL fingerprinting. No engine defaults or shared migration iterators change. Explicit source selection is validated; restore-only selects one source through resolveRestoreTarget (src/core/restore-target.ts, shared with gbrain storage status) and checks its recorded file path through the existing native path resolver. The manifest rejects unsafe paths, same/cross-source aliases, case/Unicode and file-prefix collisions before destination output, preserving the <slug>.md and .raw/<name>.json layout. Existing planned paths refuse rather than overwrite. The portable first-party native addon anchors no-follow directories and publishes leaves with atomic no-replace operations, retaining an exclusive persistent .gbrain-export-status marker; success requires flushed data and a final COMPLETE line. Unsupported native capabilities fail closed without a pathname fallback. A fresh destination is the retry path; unrelated files are never pruned. Fixed capacity/time limits fail visibly, never truncate. This is a historical snapshot, not a database backup or a sandbox against another same-user process renaming directories. See safe export. Engine-free export --help documents scope, no-overwrite publication and incomplete-output recovery. Wave B PR 2: a segmented page streams (segmentedExportMarkdown: serializeMarkdown's head (an optional revision pins the body open to that page revision, as unreadPageFile does with its snapshot's, so a page that moved since refuses instead of mixing one revision's frontmatter with the next one's body), the trusted stored body through readBodyRange under a body ledger, here exportBodyLedger, the same withdrawal overlay; restore_page of a page over the single-string ceiling passes its snapshot's ledger; the timeline separator before the first timeline byte) into its own stage file (ExportStage.addStream, a full collection per 1 MiB read), published with the native path API; its payload estimate is body_bytes, the per-page limit is exportPayloadLimit(pages.max_bytes) (32 MiB while segmented storage is off), a streamed page adds 1 ms per KiB to the 10-minute snapshot deadline and stage files must leave 512 MiB free on the staging filesystem (test/e2e/large-pages-export.test.ts: inline vs segmented same bytes at 2 and 20 MiB, export(import(F)) == F, a gated 128 MiB memory arm). exportPagePath writes a page whose slug is not a portable file name under an escaped name with its slug: line (: and other Windows-unsafe characters become ~, a reserved device name or trailing dot/space gets ~ appended, an over-budget segment is cut with a ~<8 hex> hash and marked not restorable); runExport returns an ExportReport, prints the escaped pages, and collects every ExportPathCollision into one refusal whose lines name each fix (test/pathological/b5-export-unsafe-slugs.test.ts). Pinned by both-engine export safety/independent-roundtrip/snapshot/failure-release suites, the 100001-page scale fixture with staging bytes and full export SQL statement accounting, the native publication/compiled-wrapper suite, actual CLI help tests, and the PostgreSQL export E2E wrapper. A page's file is rendered by export-snapshot.ts (inlineExportMarkdown, segmentedExportHead for segmentedExportMarkdown; frontmatter with the #5966 slug stamp), which the git-gap equality contract (persistence/git-gap.ts) shares.

  • src/commands/extract-conversation-facts.ts + src/core/cycle/conversation-facts-backfill.ts — bulk fact extraction for long-form conversation pages. Walks conversation/meeting/slack/email/imessage/imessage-daily pages, splits them into bounded windows via src/core/facts/conversation-windows.ts (#6267: eligibility per 30-min gap group of ≥2 messages decided before windowing; windows close at 30 messages or when the rendered text with its header would exceed 6,500 chars; oversized turns split at sentence boundaries with the speaker prefix repeated; a trailing single reply of an eligible group is its own window, never glued across a gap; nothing is clipped and an unrepresentable header fails the page before prior-fact cleanup; a page's frontmatter conversation_segment_gap_minutes, an integer from 1 to 10080, overrides the gap for that page, and any other value is ignored with a stderr warning naming the accepted range), prepends a topical/temporal header, and uses the strict extractFactsFromTurnWithOutcome() path so provider and output failures remain retryable instead of becoming successful empty pages. Invariants: strict per-source core (runExtractConversationFactsCore({sourceId, ...}) always takes one sourceId; CLI + cycle phase each do their own multi-source iteration because PHASE_SCOPE='source' is taxonomy-only); bounded two-phase enumeration (paginated listPages({type, sourceId, limit:10}); per-page body cap MAX_PAGE_BODY_BYTES = CONVERSATION_BODY_MAX_BYTES in conversation-parser/body.ts, PAGE_MAX_BYTES + 1 MiB = 25 MiB, measured on the parser input; readConversationBodyForParsing stats a raw_transcript sidecar and throws ConversationBodyTooLargeError over the cap before any read, the snapshot carries oversizedSidecarBytes, and a size skip writes a skipped_too_large receipt to page_extraction_state (doctor extraction_input_truncated) that a later run under the cap clears; test test/conversation-facts-oversized-sidecar.test.ts; a segmented page is read in ranges; one over CONVERSATION_WINDOW_BYTES with no conversation facts is extracted from its newest window (day-header date, tail_window receipt, window_rule: no_prior_facts); one with facts is skipped with nothing cleared (skipped_too_large, window_rule: prior_facts_kept), since the run clears prior facts the window may not see, until PR 4's window anchors (test test/large-pages/segmented-conversation-facts.test.ts)); page-global row_num accumulator (the facts unique index is (source_id, source_markdown_slug, row_num)); versioned snapshot-bound outcomes (cli:extract-conversation-facts:terminal:v2 for complete pages and a separate non-extractable:v2 source for recognized pages with no eligible segment); operation checkpoints are scheduling hints only and never suppress a replay without a matching v2 outcome; optional opts.budgetTracker? is used as-is, while an absent tracker is created with maxCostUsd (a DEFAULT cap is dropped with a warning when the extraction or parser chat model is unpriced, via src/core/facts/conversation-budget.ts conversationFactsCostCap (#5823); explicit CLI/caller/cycle caps stay fail-closed and a no_pricing stop reports budget_reason/budget_model, exits 1 and names pricing.overrides); body reads cover compiled truth, timeline, and configured raw-transcript sidecars; facts.extraction_enabled kill-switch with --override-disabled; --types LIST allowlist (conversation,meeting,slack,email,imessage,imessage-daily); --background via maybeBackground; and speaker-shaped-fold decline — when the parse reports unrecognized_headings containing a speaker-shaped label (1-2 title-cased words, not in the doc-heading stoplist — the stoplist gates the DECLINE only, so a miss is warn-noise, never data loss) AND the parse produced fewer than two distinct speakers, the page is declined instead of extracted under wrong attribution: counted in pages_skipped_unrecognized_speaker (Result/CLI/cycle surfaces), warned to stderr with the folding pattern id, and deliberately NON-terminal (no durable audit row and no orphan cleanup, so a future parser/pattern fix retries the page); multi-speaker pages with folds proceed warn-only. publishConversationFacts skips a non-outcome row an active conversation fact of the source already states (findCaptureDuplicate, no time bound; duplicates_skipped, #7043). The companion conversation_facts_backfill cycle phase is default-off, iterates every source except cycle.conversation_facts_backfill.exclude_sources (reported as sources_excluded), reports managed pages left accepted and still publishing as pages_pending in its details and summary (test/cycle-conversation-facts-backfill-pending-7500.test.ts), and enforces per-source plus brain-wide cost and wall-time caps. Migration v94 provides the partial facts index used by outcome lookups. computeConversationFactsBacklogCheck reports fresh completed, scanned-not-extractable, and unfinished counts separately, warning when more than 10 eligible pages lack a fresh v2 outcome. sources audit exposes facts_backfill_estimate: {pages, est_segments, est_cost_usd, types}. --workers N for LLM-bound fact extraction over conversation pages, with a per-page advisory lock via src/core/db-lock.ts:withRefreshingLock (lock id extract-conversation-facts:<source>:<slug>, TTL PER_PAGE_LOCK_TTL_MINUTES=2 with 20s refresh via Math.max(15s, 120s/6); LockUnavailableError triggers skip-and-continue with rate-limited log per (source, minute) + pages_lock_skipped counter + CLI exits 3 when non-zero AND no hard failures). A page's rows are buffered and published once after its last segment (publishPageFacts on an unmanaged brain, one writeDerivedFacts transaction; the managed batch otherwise), through publishConversationFacts (facts/conversation-publication.ts), so a crashed, failed, empty or partial run never removes the prior batch and a terminal audit row commits only with its page's facts (#7013); a run's scope is partial when fewer segments than in scope ran, window when --since dropped messages, else full, and a page that changed mid-run keeps an unmanaged run's facts as a partial batch. assertFactsEmbeddingDimMatchesConfig(engine) is the startup preflight (throws FactsEmbeddingDimMismatchError with paste-ready ALTER hint BEFORE the first insert; cached per engine via WeakMap). Result type carries pages_lock_skipped + orphan_facts_cleaned. Additive pages_skipped_unparsed, pages_skipped_type_mismatch, pages_skipped_insufficient_turns, and pages_skipped_since explain the unchanged pages_skipped aggregate across core, CLI, workers, and cycle sources; durable completion remains separate. --dry-run stops after segmentation, with no parser-fallback, extractor, or embedding calls and no durable knowledge/checkpoint/receipt/rollup writes. The narrow python-dict-utterance registry format and its quoted/nested-example rejection are documented in conversation parser patterns. Checkpoint state is a shared cpMap: Map<slug, endIso> (NOT a per-page-mutated cpEntries: string[]) so atomic Map.set survives parallel workers. Minion handler extract-conversation-facts in src/commands/jobs.ts round-trips workers via job.data.workers for --background --workers 20. Cycle config key cycle.conversation_facts_backfill.workers (default 1; opt-in concurrency under brain-wide cost + walltime caps). Pinned by test/extract-conversation-facts-diagnostics.serial.test.ts (pool workers, per-page lock skip + exit 3, replay replacing a prior partial run's facts, D15 preflight, --workers round-trip). src/commands/doctor.ts reads the same outcomes, which survive checkpoint GC. Each outcome is bound to the exact parsed snapshot: regular pages use content_hash plus the UTC effective date; raw-conversation sidecars and legacy null-hash pages use a canonical SHA-256 over every parser-relevant input. Selection checks the token before locking, refetches under the lock, and verifies it again before writing the outcome, so an edit cannot be certified by stale work. The strict extraction path treats provider, refusal, truncation, malformed/schema-invalid output, segment-write, cleanup, and terminal-write failures as unfinished work; bulk failures increment pages_failed, affect CLI/cycle receipts and exit status, and never advance the legacy checkpoint. Explicit slugs batches contain page failures like the pool (cancellation and budget stops halt); logs carry only the closed reason and a retry command. Completion requires every in-scope segment (exactly --segment-limit counts). Extracted rows take facts.default_visibility (resolved once per run); audit rows stay private. Each page's own entities go to the extractor as entityHints (slugs, src/core/facts/conversation-entity-hints.ts, computed once per page, cap CONVERSATION_ENTITY_HINTS_CAP = 40 through ExtractInput.entityHintsCap): authored edges only (the page's frontmatter edges with the page as origin, then outgoing markdown, wikilink-resolved and manual links), same source, live fact-entity pages, and a private entity only when the run's facts are private; the extract_facts op keeps its 5-hint cap and prompt. Pinned by test/conversation-entity-hints.test.ts. Checkpoints are only a scheduling hint: a slug without a matching v2 outcome is replayed. no_match, errors, cancellation, and dry runs never become durable negatives, bar facts/conversation-skip.ts (prose meetings, single emails, undated turns). Result, CLI, cycle, and doctor surfaces keep completed, scanned-not-extractable, unfinished, failed, and lock-skipped counts separate. See Conversation backfill durable outcomes for the operator and maintainer contract. Pinned by test/extract-conversation-facts.test.ts and test/doctor-conversation-facts-backlog.test.ts. --dry-run also prints the paid-run estimate (facts/conversation-budget.ts conversationRunEstimate: segments, input and output tokens and dollars on the configured chat model, or a pricing set hint for an unpriced model; JSON estimate). On a managed brain the core runs managedDerivedFactsPreflight (local writer, active source) before any provider work, and a page's facts and terminal (or non-extractable) audit row are buffered, then published in its receipted batch after source activity, page id, revision and parser-input snapshot are rechecked under the page lock, so a failed or raced re-extraction keeps the prior batch; the CLI no longer refuses up front and receipt pages are skipped. Tests: test/managed-facts-writers.test.ts, test/managed-unsupported-preflight.serial.test.ts (refusal before spend for an unaccepted writer).

Continue this subsystem.