Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(synthesize_concepts): an unchanged concept banks its lost member provenance again (#7548)

garrytana5cc8259bbc3
diff --git a/docs/architecture/key-files/agent-bootstrap-continued.md b/docs/architecture/key-files/agent-bootstrap-continued.md
index 1d3a06657b..de5f200a01 100644
--- a/docs/architecture/key-files/agent-bootstrap-continued.md
+++ b/docs/architecture/key-files/agent-bootstrap-continued.md
@@ -35,5 +35,5 @@
- `src/core/bootstrap/verify.ts` + `status.ts` — verify is the definition of done: fail-soft check suite over the REAL write path (put_page op, waiting as long as a CLI write: `resolveCliWriteWaitMs`, so `GBRAIN_WRITE_WAIT_MS`/`persistence.write_wait_ms`, default 30 s; a write still pending after that names its request and `gbrain write-request` poll command → write-through file under `brain/` → in-process sweep → graph floor via link tables → recall), the keyless magic-moment check (`## Facts` fence → zero-LLM reconciliation → world-visibility read-back), source_id collision resolution (as the one bootstrap subcommand holding an engine: a manifest `source_id` already registered to a DIFFERENT checkout → derives a stable `workspace-<8char-path-hash>`, persists it to agent.json, names the re-register steps — every consumer reads `manifest.source_id`), the `embedding_plane` check (keyed installs live-embed ONE probe string and compare the RETURNED width to the actual `content_chunks.embedding` width — a plane split is a named FAIL with the recovery command, keyless passes, a dead probe warns; runs BEFORE the roundtrip so a keyless-passing roundtrip can never certify a brain whose keyed writes all fail), token sweep, byte floors, secret scan, deny globs, repo privacy, hooks smoke (in-process IPC), capability report, first-run tour; snapshots kept last-5 under `<home>/bootstrap/`. The roundtrip's probe section runs under one try/finally, so both fixed-slug probes are removed on every exit, early failure returns included (#6001; pinned by the early-exit case in `test/bootstrap-verify.serial.test.ts`). On a managed brain each probe is purged through the coordinator and its purge tombstones (page, plus the fact/take purges of that request) are then cleared with the host-only `unpurgePage`, also on every sweep, so the constant probe bodies are never refused `purged_content` on the next run and `page_purges` does not grow (#6634). status owns the ordered PHASES list (the runbook defers to it), artifact-first detection, install.jsonl, the runbook version-stamp skew check, and the support blob doctor/agents relay verbatim.
- `src/core/bootstrap/template-repo.ts` + `scripts/generate-template-repo.ts` — deterministic public-template generation (render `--minimal` + placeholder manifest + stamped README); published only by the release workflow after diffing against the vendored tree.
- `scripts/check-bootstrap-tag.sh` / `scripts/check-bootstrap-templates.sh` — CI guards: sanctioned distribution ref only (`latest-stable`; the release job advances it after assets publish) + runbook stamp == VERSION; template↔question-bank token bijection + placeholder-only assertion + offline generator↔vendored byte-diff + runbook-phase↔status.ts consistency. Both skip gracefully when their subjects are absent.
-- `src/core/cycle/synthesize-concepts.ts` concept-quality addendum — a `concepts/<x>` page whose frontmatter lacks `synthesized_by: synthesize_concepts-*` belongs to a human or another writer: the phase checks it before any LLM spend, never rewrites it, and reports it in `details.skipped_human_owned` (pinned by `test/cycle/synthesize-concepts-human-owned.test.ts`). Concept refs are normalized before grouping (`conceptStemFor`: last path segment through `slugifySegment`, validated by `validatePageSlug`; one atom counts once per concept), so case and spacing variants share one page and no slug carries a space; punctuation variants (`network-effects` / `networkeffects`) fold per run through `cycle/concept-redirects.ts` `addSpellingRedirects` (#5965; documented with `concept-publication.ts` in `core-cycle-continued.md`). Each page records `member_hash` (member atom slugs, titles and bodies without their `## Facts` / `## Takes` sections, which the prompt also omits, plus the synthesis model; a page still carrying the full-body hash whose inputs are unchanged is rehashed without a model call, `details.rehashed`; a narrative a `chat_fallback_chain` model wrote is hashed under that model, so the next cycle re-synthesizes it); an unchanged hash on an `llm` or `deterministic_tier` page is skipped without spend (`details.skipped_unchanged`), and a budget or error fallback never replaces an existing `llm` narrative (`details.kept_existing_narrative`); fallback pages retry next cycle. Pinned by `test/cycle/synthesize-concepts-identity.test.ts`. Eligible groups are processed deterministically by tier, descending atom count, then concept slug so the fixed LLM budget reaches the strongest evidence first regardless of database row order. Every page and phase receipt distinguishes `llm`, intended `deterministic_tier`, `budget_fallback`, and `error_fallback` synthesis modes. The narrative call's output cap is sized from the resolved `models.dream.synthesize` model via `resolveSynthMaxOutputTokens`: 500 for non-thinking models, the gateway's `THINKING_MODEL_MAX_OUTPUT_TOKENS` (no phase-private number — DeepSeek v4 truncates at 8192-class caps) when the gateway's shared `isThinkingModel` matches (name-matched Claude 5 or recipe-declared `thinking_by_default`; unknown providers count as non-thinking), so a tier-`reasoning` thinking model no longer spends the whole budget on reasoning and persists a template stub or truncated chain-of-thought as the concept narrative. Pinned by `test/cycle/synthesize-concepts-token-cap.test.ts`. Right after each concept page write the phase banks concept<->member-atom provenance edges through `engine.addLinksBatch` (`link_source: 'concept-provenance'`; `synthesized_from` concept->atom, `synthesizes` atom->concept; audit site `cycle.synthesize_concepts.provenance`), both endpoints scoped to the cycle's source, so the concept pages are graph-reachable (backlinks, relational recall, doctor `graph_signals_coverage`/`orphans`) even though the prompt forbids enumerating atoms in the body. The dedicated `link_source` keeps reconcile passes from pruning them; `ON CONFLICT DO NOTHING` makes re-runs the backfill; a failed or zero-row edge write lands in `link_warnings[]` (phase `warn`) — NOT in `failures[]`, which means "LLM-failed → template fallback" downstream and drives the rollup's `halt_delta`/`round_completed_delta` — and never aborts the page write. Atom discovery (the `type = 'atom'` scan) is scoped to the cycle source (`opts.sourceId ?? 'default'`) so same-slug atoms from other sources are never grouped into this source's concepts. Pinned by the `#4589` describe in `test/cycle/extract-atoms-synthesize-concepts.test.ts` and `test/cycle/synthesize-concepts-source-scope.test.ts`. The phase budget is `cycle.synthesize_concepts.budget_usd` (finite USD above 0, default 1.5; `config set` refuses other values, a stored invalid value keeps the default with a named-key warning, specs in `src/core/cycle/phase-config-values.ts`); groups refused at the cap are counted in the summary and `details.warnings`. Pinned by `test/cycle-synthesize-concepts-budget-config.test.ts`. A narrative whose stop reason is `length`, `refusal` or `content_filter` is a failure (template fallback for a new concept; an existing `llm` page and its `member_hash` stay), and failed narratives are bounded per concept and member hash by `cycle/concept-retry-bound.ts` (`ConceptRetryBound`, DB-only config key `dream.concepts.failed_attempts`, `MAX_CONCEPT_ATTEMPTS` = 3): a bounded concept is skipped before any spend into `details.skipped_retry_bound` until its members change, a narrative succeeds, or the key is unset (`test/cycle/synthesize-concepts-stop-reason.test.ts`).
+- `src/core/cycle/synthesize-concepts.ts` concept-quality addendum — a `concepts/<x>` page whose frontmatter lacks `synthesized_by: synthesize_concepts-*` belongs to a human or another writer: the phase checks it before any LLM spend, never rewrites it, and reports it in `details.skipped_human_owned` (pinned by `test/cycle/synthesize-concepts-human-owned.test.ts`). Concept refs are normalized before grouping (`conceptStemFor`: last path segment through `slugifySegment`, validated by `validatePageSlug`; one atom counts once per concept), so case and spacing variants share one page and no slug carries a space; punctuation variants (`network-effects` / `networkeffects`) fold per run through `cycle/concept-redirects.ts` `addSpellingRedirects` (#5965; documented with `concept-publication.ts` in `core-cycle-continued.md`). Each page records `member_hash` (member atom slugs, titles and bodies without their `## Facts` / `## Takes` sections, which the prompt also omits, plus the synthesis model; a page still carrying the full-body hash whose inputs are unchanged is rehashed without a model call, `details.rehashed`; a narrative a `chat_fallback_chain` model wrote is hashed under that model, so the next cycle re-synthesizes it); an unchanged hash on an `llm` or `deterministic_tier` page is skipped without spend (`details.skipped_unchanged`), and when its concept-provenance edges no longer reach every member they are banked again at its current revision without a publication (`details.provenance_restored`, `test/cycle/synthesize-concepts-provenance-restore.test.ts`), and a budget or error fallback never replaces an existing `llm` narrative (`details.kept_existing_narrative`); fallback pages retry next cycle. Pinned by `test/cycle/synthesize-concepts-identity.test.ts`. Eligible groups are processed deterministically by tier, descending atom count, then concept slug so the fixed LLM budget reaches the strongest evidence first regardless of database row order. Every page and phase receipt distinguishes `llm`, intended `deterministic_tier`, `budget_fallback`, and `error_fallback` synthesis modes. The narrative call's output cap is sized from the resolved `models.dream.synthesize` model via `resolveSynthMaxOutputTokens`: 500 for non-thinking models, the gateway's `THINKING_MODEL_MAX_OUTPUT_TOKENS` (no phase-private number — DeepSeek v4 truncates at 8192-class caps) when the gateway's shared `isThinkingModel` matches (name-matched Claude 5 or recipe-declared `thinking_by_default`; unknown providers count as non-thinking), so a tier-`reasoning` thinking model no longer spends the whole budget on reasoning and persists a template stub or truncated chain-of-thought as the concept narrative. Pinned by `test/cycle/synthesize-concepts-token-cap.test.ts`. Right after each concept page write the phase banks concept<->member-atom provenance edges through `engine.addLinksBatch` (`link_source: 'concept-provenance'`; `synthesized_from` concept->atom, `synthesizes` atom->concept; audit site `cycle.synthesize_concepts.provenance`), both endpoints scoped to the cycle's source, so the concept pages are graph-reachable (backlinks, relational recall, doctor `graph_signals_coverage`/`orphans`) even though the prompt forbids enumerating atoms in the body. The dedicated `link_source` keeps reconcile passes from pruning them; `ON CONFLICT DO NOTHING` makes re-runs the backfill; a failed or zero-row edge write lands in `link_warnings[]` (phase `warn`) — NOT in `failures[]`, which means "LLM-failed → template fallback" downstream and drives the rollup's `halt_delta`/`round_completed_delta` — and never aborts the page write. Atom discovery (the `type = 'atom'` scan) is scoped to the cycle source (`opts.sourceId ?? 'default'`) so same-slug atoms from other sources are never grouped into this source's concepts. Pinned by the `#4589` describe in `test/cycle/extract-atoms-synthesize-concepts.test.ts` and `test/cycle/synthesize-concepts-source-scope.test.ts`. The phase budget is `cycle.synthesize_concepts.budget_usd` (finite USD above 0, default 1.5; `config set` refuses other values, a stored invalid value keeps the default with a named-key warning, specs in `src/core/cycle/phase-config-values.ts`); groups refused at the cap are counted in the summary and `details.warnings`. Pinned by `test/cycle-synthesize-concepts-budget-config.test.ts`. A narrative whose stop reason is `length`, `refusal` or `content_filter` is a failure (template fallback for a new concept; an existing `llm` page and its `member_hash` stay), and failed narratives are bounded per concept and member hash by `cycle/concept-retry-bound.ts` (`ConceptRetryBound`, DB-only config key `dream.concepts.failed_attempts`, `MAX_CONCEPT_ATTEMPTS` = 3): a bounded concept is skipped before any spend into `details.skipped_retry_bound` until its members change, a narrative succeeds, or the key is unset (`test/cycle/synthesize-concepts-stop-reason.test.ts`).
- `src/core/bootstrap/harness-cleanup.ts` — #6743 shared-skills cleanup convergence for the harness apply (step 10), `--status` and doctor's `bootstrap_harness_health`. `convergeHarnessCleanup` leaves stale enrollments (a working prior enrollment stays until the current one is ready; one whose credential is already revoked always leaves) and then revokes each carried `previous_ids` entry that no not-yet-left enrollment holds, one id at a time. `leaveRevokedEnrollment` runs the adapter's local leave with a caller that never contacts the host and records the entry left with reason `credential_revoked`: a revoked principal cannot authenticate `leave_brain`, so its membership is inert. `harnessCleanupItems` reports what stays pending per id (`revoke_pending`, `leave_pending`, `enrollment_retained`, `credential_unreadable`, with the token-row state from the read-only `tokenStatesWith` lookup); the apply and `--status` exit `bootstrap_cleanup_pending` (14) with a `fix` that re-runs the same command when every id converges and otherwise names the owner's revoke or restore step. Pinned by `test/bootstrap-harness-cleanup-6743.test.ts`.
diff --git a/src/core/cycle/concept-writes.ts b/src/core/cycle/concept-writes.ts
index b498b00eff..d9bef69049 100644
--- a/src/core/cycle/concept-writes.ts
+++ b/src/core/cycle/concept-writes.ts
@@ -87,8 +87,13 @@ export function conceptWriter(deps: ConceptWriterDeps) {
* as a warn, the page write stands. Mirrors #3961. Returns whether the concept now goes to world.
*/
const bankProvenance = async (write: ConceptWrite): Promise<boolean> => {
+ if (write.synthesisMode === 'llm') deps.retries.succeed(`${src}:${write.conceptSlug}`);
+ await bankLinks(write);
+ return write.visibility === 'world' && !write.covered && await conceptProvenanceCovers(engine, src, write.conceptSlug, write.atomSlugs);
+ };
+ /** The edges of a concept at `write.revision` (managed) or its current revision (unmanaged); a failure is a link warning. */
+ const bankLinks = async (write: Pick<ConceptWrite, 'concept' | 'conceptSlug' | 'atomSlugs' | 'revision'>): Promise<void> => {
const { conceptSlug } = write;
- if (write.synthesisMode === 'llm') deps.retries.succeed(`${src}:${conceptSlug}`);
const provenanceLinks: LinkBatchInput[] = [...new Set(write.atomSlugs)].flatMap((atomSlug) => [
{ from_slug: conceptSlug, to_slug: atomSlug, link_type: 'synthesized_from', link_source: 'concept-provenance', context: 'member atom', from_source_id: src, to_source_id: src },
{ from_slug: atomSlug, to_slug: conceptSlug, link_type: 'synthesizes', link_source: 'concept-provenance', context: 'concept synthesized from this atom', from_source_id: src, to_source_id: src },
@@ -112,7 +117,6 @@ export function conceptWriter(deps: ConceptWriterDeps) {
deps.linkWarnings.push({ concept: write.concept, warning: `provenance links failed: ${msg}` });
console.error(`[synthesize_concepts] provenance links failed for ${conceptSlug} (non-fatal): ${msg}`);
}
- return write.visibility === 'world' && !write.covered && await conceptProvenanceCovers(engine, src, conceptSlug, write.atomSlugs);
};
/** One managed batch; each concept settles on its own, and the ones that published carry their new revision. */
const publishManaged = async (writes: ConceptWrite[], pageVisibility: (write: ConceptWrite) => Visibility): Promise<ConceptWrite[]> => {
@@ -150,5 +154,7 @@ export function conceptWriter(deps: ConceptWriterDeps) {
},
/** Managed: publish whatever is queued. */
flush,
+ /** #7548: an unchanged concept whose edges no longer reach every member banks them again, with no publication. */
+ restoreProvenance: bankLinks,
};
}
diff --git a/src/core/cycle/synthesize-concepts.ts b/src/core/cycle/synthesize-concepts.ts
index 49e29b5226..d9e0722978 100644
--- a/src/core/cycle/synthesize-concepts.ts
+++ b/src/core/cycle/synthesize-concepts.ts
@@ -329,6 +329,7 @@ export async function runPhaseSynthesizeConcepts(
const skippedHumanOwned: string[] = [];
const skippedDeleted: string[] = [];
const skippedUnchanged: string[] = [];
+ const provenanceRestored: string[] = [];
const rehashed: string[] = [];
const keptExistingNarrative: string[] = [];
const pricingOverrides = await loadPricingOverrides(engine);
@@ -372,16 +373,18 @@ export async function runPhaseSynthesizeConcepts(
const memberHash = hashFor(hashModel);
const priorMode = existing?.frontmatter?.synthesis_mode;
const realNarrative = priorMode === 'llm' || priorMode === 'deterministic_tier';
- if (existing?.frontmatter?.member_hash === memberHash && realNarrative) {
- skippedUnchanged.push(conceptSlug);
- continue;
- }
// #7269: rewriting a deterministic page to the template it already holds, at a visibility it already has, would
// publish nothing new (a page hashed with the model before the fix keeps its body and is not rewritten).
const priorVisibility: Visibility = existing?.frontmatter?.visibility === 'private' ? 'private' : 'world';
- if (hashModel === '' && priorMode === 'deterministic_tier' && strictestVisibility([group.visibility, priorVisibility]) === priorVisibility
- && stripFenceSections(existing!.compiled_truth).trim() === deterministicNarrative(group).trim()) {
+ if ((existing?.frontmatter?.member_hash === memberHash && realNarrative)
+ || (hashModel === '' && priorMode === 'deterministic_tier' && strictestVisibility([group.visibility, priorVisibility]) === priorVisibility
+ && stripFenceSections(existing!.compiled_truth).trim() === deterministicNarrative(group).trim())) {
skippedUnchanged.push(conceptSlug);
+ // #7548: the cache skips the model, not the member provenance an unchanged concept may have lost.
+ if (!opts.dryRun && !await conceptProvenanceCovers(engine, src, conceptSlug, group.atomSlugs)) {
+ await writer.restoreProvenance({ concept: group.conceptSlug, conceptSlug, atomSlugs: group.atomSlugs, revision: existingSnapshot!.revision });
+ provenanceRestored.push(conceptSlug);
+ }
continue;
}
// #6643 (B1): a drifted concept would only add a conflict receipt per publication; checked live before any spend.
@@ -593,6 +596,7 @@ export async function runPhaseSynthesizeConcepts(
skipped_human_owned: skippedHumanOwned,
skipped_deleted: skippedDeleted,
skipped_unchanged: skippedUnchanged,
+ provenance_restored: provenanceRestored,
rehashed,
kept_existing_narrative: keptExistingNarrative,
skipped_retry_bound: skippedRetryBound,
diff --git a/test/cycle/synthesize-concepts-provenance-restore.test.ts b/test/cycle/synthesize-concepts-provenance-restore.test.ts
new file mode 100644
index 0000000000..9618dc3c0e
--- /dev/null
+++ b/test/cycle/synthesize-concepts-provenance-restore.test.ts
@@ -0,0 +1,86 @@
+/**
+ * #7548: an unchanged concept still restores its member provenance.
+ *
+ * Protects: a concept whose member hash is unchanged spends nothing, and when
+ * its concept-provenance edges no longer reach every member atom (a link lost
+ * to a failed write, a concurrent move or a deletion) the run banks them again
+ * at the concept's current revision, without a model call and without
+ * duplicating an edge.
+ * Fails when: the unchanged-hash shortcut skips the provenance writer, so the
+ * concept stays disconnected from its members on every later run.
+ * Why new: g7-concept-provenance-edges covers changed member groups only.
+ */
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { BrainEngine } from '../../src/core/engine.ts';
+import type { ChatResult } from '../../src/core/ai/gateway.ts';
+import { runPhaseSynthesizeConcepts } from '../../src/core/cycle/synthesize-concepts.ts';
+import { _resetWriteThroughCacheForTest } from '../../src/core/write-through.ts';
+import { isolatedSharedSkillsEngine } from '../helpers/shared-skills-engine.ts';
+import { managedBrain } from '../helpers/managed-brain.ts';
+import { withEnv } from '../helpers/with-env.ts';
+
+const MODEL = 'anthropic:claude-sonnet-4-6';
+const CONCEPT = 'concepts/storage-example';
+const ATOMS = [0, 1, 2, 3, 4].map(i => ({ slug: `atoms/storage-${i}`, concept_refs: [CONCEPT], body: `Atom ${i} about storage.`, title: `storage atom ${i}` }));
+const expected = ATOMS.flatMap(a => [`${CONCEPT} synthesized_from ${a.slug}`, `${a.slug} synthesizes ${CONCEPT}`]).sort();
+
+const edges = async (engine: BrainEngine) => (await engine.executeRaw<{ e: string }>(
+ `SELECT f.slug || ' ' || l.link_type || ' ' || t.slug AS e FROM links l JOIN pages f ON f.id=l.from_page_id JOIN pages t ON t.id=l.to_page_id
+ WHERE l.link_source='concept-provenance' ORDER BY 1`)).map(r => r.e);
+
+async function scenario(engine: BrainEngine, brainDir?: string) {
+ let calls = 0;
+ const chat = async (): Promise<ChatResult> => {
+ calls++;
+ const text = 'A complete narrative about this concept.';
+ return { text, blocks: [{ type: 'text', text }], stopReason: 'end', usage: { input_tokens: 10, output_tokens: 10, cache_read_tokens: 0, cache_creation_tokens: 0 }, model: MODEL, providerId: 'anthropic' };
+ };
+ const run = () => runPhaseSynthesizeConcepts(engine, { _atoms: ATOMS, _chat: chat, brainDir });
+ await run();
+ expect(calls).toBe(1);
+ expect(await edges(engine)).toEqual(expected);
+ const revision = (await engine.readPageSnapshot(CONCEPT, { sourceId: 'default' }))!.revision;
+
+ await engine.executeRaw(`DELETE FROM links WHERE link_source='concept-provenance'
+ AND (from_page_id = (SELECT id FROM pages WHERE slug='atoms/storage-1') OR to_page_id = (SELECT id FROM pages WHERE slug='atoms/storage-1'))`);
+ const repaired = await run();
+ expect(calls).toBe(1);
+ expect(repaired.details.skipped_unchanged).toEqual([CONCEPT]);
+ expect(await edges(engine)).toEqual(expected);
+ expect(repaired.details.provenance_restored).toEqual([CONCEPT]);
+ expect((await engine.readPageSnapshot(CONCEPT, { sourceId: 'default' }))!.revision).toBe(revision);
+
+ const again = await run();
+ expect(calls).toBe(1);
+ expect(again.details.provenance_restored).toEqual([]);
+ expect(await edges(engine)).toEqual(expected);
+}
+
+describe('unchanged concept restores member provenance (#7548)', () => {
+ test('unmanaged brain', async () => {
+ const home = mkdtempSync(join(tmpdir(), 'gbrain-7548-'));
+ try {
+ await withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
+ _resetWriteThroughCacheForTest();
+ const { engine, close } = await isolatedSharedSkillsEngine();
+ try {
+ await engine.setConfig('models.dream.synthesize', MODEL);
+ for (const atom of ATOMS) await engine.putPage(atom.slug, { type: 'note', title: atom.title, compiled_truth: atom.body, timeline: '', frontmatter: {} });
+ await scenario(engine);
+ } finally { await close(); }
+ });
+ } finally { rmSync(home, { recursive: true, force: true }); }
+ }, 240_000);
+
+ test('managed brain', async () => {
+ await managedBrain(async ({ engine, root }) => {
+ await engine.setConfig('models.dream.synthesize', MODEL);
+ await scenario(engine, root);
+ }, { setup: async ({ engine }) => {
+ for (const atom of ATOMS) await engine.putPage(atom.slug, { type: 'note', title: atom.title, compiled_truth: atom.body, timeline: '', frontmatter: {} });
+ } });
+ }, 240_000);
+});