feat(improvement): restore approved knowledge baseline

[drewstone]

Problem

Knowledge candidates could be applied safely, but an approved rollback required consumers to recreate the package's file transaction and recovery logic.

Solution

Add restoreKnowledgeCandidateBaseline() and share one apply/restore implementation over the existing frozen snapshots, content identities, locks, and resumable file journal. Restoring returns the run to candidate-ready, so the same measured candidate can be reviewed and applied again without a schema change.

Verification

• pnpm test: 285 passed, 10 skipped
• pnpm typecheck
• pnpm lint: 98 files
• pnpm build
• pnpm verify:package: clean install, five imports, CLI version, and re-pack
• Independent GPT-5.5 review: no findings

[tangletools]

✅ Auto-approved drewstone PR — 06febc98

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-17T22:46:13Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	1 (1 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	139.8s (2 bridge agents)
Total	139.8s

💰 Value — sound

Adds restoreKnowledgeCandidateBaseline() to revert a promoted candidate back to its frozen baseline by unifying promote/restore over one shared transition path — coherent, reuses existing crash-safe primitives, no existing equivalent.

• What it does: Introduces a new public API restoreKnowledgeCandidateBaseline() (src/kb-improvement.ts:595). After a candidate has been promoted (live KB == candidate content), this writes the frozen baseline snapshot back to the live root via a fresh file transaction, sets the run state back to 'candidate-ready', clears promotedCandidateId, and records a 'candidate.restored' ledger event — so the same measured c
• Goals it achieves: Let an operator undo an approved promotion through the package's own API instead of hand-rolling the file transaction, snapshot lookup, locking, resumability, and ledger bookkeeping. Secondary goal, achieved in the same edit: collapse the previously promotion-only apply path into a single direction-parameterized transition so that restore inherits promotion's crash-recovery, lease, snapshot-identi
• Assessment: Good change, built in the grain of the codebase. The unify-vs-duplicate choice is the right one: applyKnowledgeCandidateTarget (src/kb-improvement.ts:855) keeps ONE body for lease acquire, withKnowledgeMutation, measured-snapshot + baseline-snapshot handling, prepare/apply/rollback/finish transaction orchestration, state persistence, and event idempotency — ~150 lines of intricate resumability log
• Better / existing approach: none — this is the right approach. I checked for a pre-existing equivalent and there is none: grep for unpromote|restoreBaseline|revertPromotion|discardPromotion across src/ returns nothing, and 'candidate.restored'/'restore.blocked' event types are newly introduced by this PR. The obvious-looking alternative — reuse file-transaction.ts's rollbackKnowledgeFileTransaction / direction:'rollback' — d
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound-with-nits

A clean candidate-level baseline restore that refactors promotion into one shared, bidirectional transition over existing primitives — net-new capability, in the grain of the codebase, with only a minor naming nit.

• Integration: Reachable and wired correctly. restoreKnowledgeCandidateBaseline is exported via src/index.ts:20 (export * from './kb-improvement'), matching how promoteKnowledgeCandidate (src/kb-improvement.ts:588) is exposed. No internal caller exists in this repo — but that is the established pattern for the candidate-transition API surface (promote has no internal caller either; both are programmatic li
• Fit with existing patterns: Fits the established pattern precisely. It reuses the same four primitives promotion uses — frozen baseline snapshot (withBaselineSnapshot, src/kb-improvement.ts:1734), measured candidate snapshot (withMeasuredCandidateSnapshot), resumable file transaction journal (prepareKnowledgeFileTransaction / finishKnowledgeFileTransaction), and run lease (acquireRunLease) — and does NOT compete wi
• Real-world viability: Holds up beyond the happy path. The implementation reuses promotion's full safety envelope: lease + mutation lock ownership re-asserted at every mutation boundary (src/kb-improvement.ts:941, 970, 998), rollback-on-failure with AggregateError if cleanup also fails (954-959, 1012-1017), and content-hash post-condition (hashKnowledgeBase(input.root) !== desiredHash, line 977). Concurrency is hand
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🎯 Usefulness Audit

🟡 Restore options type is an alias of PromoteKnowledgeCandidateOptions [ergonomics] ``

src/kb-improvement.ts:397 exports RestoreKnowledgeCandidateBaselineOptions = PromoteKnowledgeCandidateOptions. The shape is genuinely identical (root, candidate, ownerId, leaseTtlMs, now, onState), so reuse is reasonable and callers writing restoreKnowledgeCandidateBaseline({ root, candidate }) never spell the type name — not adoption-blocking. But the Promote... name surfaces in IDE hover/JSDoc for a restore call, which is mildly confusing. A KnowledgeCandidateTransitionOptions rename (

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260717T225032Z}