feat(improvement): promote exact knowledge candidates

[drewstone]

Problem

Knowledge improvement could measure a candidate and later promote different mutable bytes.
Filesystem stores silently kept parts of their state in memory, concurrent writers could interleave, and a crash could leave mixed knowledge files or an opaque blocked root.
Cost accounting also accepted caller-reported estimates outside the shared paid-call API.

Solution

• Bind every approved candidate to its goal, live-base hash, frozen candidate hash, evidence hash, and exact promotion-plan hash.
• Keep candidate work outside the live knowledge base; approval applies the measured bytes without rerunning research or generation.
• Refuse promotion when the live base, candidate snapshot, evidence, or file plan changed.
• Route every package writer through one root lock and one durable multi-file transaction implementation.
• Persist all filesystem-backed sources, pages, and events; pure reads no longer create state.
• Resume interrupted writes automatically for their owning operation.
• Expose inspectPendingKnowledgeMutation() and exact-ID recoverPendingKnowledgeMutation() for explicit apply or rollback without force-unlocking; contradictory recovery requests fail.
• Route paid benchmark and memory calls through context.cost.runPaidCall() from @tangle-network/agent-eval@0.118.3; deterministic work reports zero cost.
• Remove the old automatic-promotion and mutable-candidate API shape. This is the package's intentional 2.0.0 contract.

Proof

• pnpm typecheck: passed.
• pnpm test: 28 files passed, 2 skipped; 278/278 runnable tests passed, 10 opt-in/live tests skipped.
• Focused durability/candidate tests: 61/61 passed.
• pnpm build: passed.
• pnpm lint: 96 files passed.
• Packed /tmp/tangle-network-agent-knowledge-2.0.0.tgz installed into an empty consumer; public promotion and recovery imports plus empty-root inspection passed.
• Recovery tests prove complete, rollback, wrong-ID rejection, no mixed read, crash resume, changed-base rejection, changed-candidate rejection, deletion, mode-only changes, and writer serialization.
• Independent review found and then approved the recovery-direction fix; a started rollback can no longer be mislabeled or reversed by an apply request.

Compatibility

This intentionally changes the persisted improvement-run state and public promotion contract.
The README contains the 1.x migration summary; package semver is 2.0.0 because 1.12.1 is already public.

[tangletools]

✅ Auto-approved drewstone PR — 31fa2ae7

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-14T04:29:31Z}

[tangletools]

⚠️ Review Interrupted — 31fa2ae7

The review runner stopped before publishing a final verdict: webhook_restarted.

State	Detail
Interrupted	webhook restarted

No review verdict was produced for this run. Trigger a fresh review on the current PR head if the PR is still open.

_{tangletools · #63 · model: kimi-for-coding · updated 2026-07-14T04:31:38Z}

[tangletools]

✅ Auto-approved drewstone PR — 76491951

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-14T04:34:12Z}