Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
v0.12.0 - Brain Integrity Suite: typed collision detection, content-hash drift, durable dream workruns (#36)
Sol Aitken84886d1b9fa2
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex add6018a..0b33f282 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.11.0",+ "version": "0.12.0","description": "Plugin-first second brain package for AI agents and humans.","author": {"name": "Open Second Brain contributors"diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 6c9a653e..57455fd8 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.11.0",+ "version": "0.12.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","skills": "./skills","hooks": "./hooks/hooks.json",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 56d27a66..e64791a2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [0.12.0] - 2026-05-26++Brain Integrity Suite: the write path for confirmed preferences is now+auditable, gated, and survivable. Promotion to `confirmed` stamps a+content-hash so the doctor can detect silent hand-edits. Every brain+write goes through `writePreferenceTxn`, a sync chokepoint that wraps+`fs.openSync(target + '.lock', 'wx')` for cross-process safety and a+chain of typed-error expectations (`StaleUpdate`, `UnsafeShrink`,+`SourceLock`, `DuplicateWrite`). Dream pass invocations open a durable+JSONL workrun so a crash mid-run leaves an inspectable trail. A new+`brain_review_candidates` MCP tool projects the next dream invocation+without mutating anything. The destructive-from-confirmed retire gate+refuses to retire a high-evidence confirmed pref through a single+weak signal when the operator opts in via config.++### Added++- `src/core/brain/sync-lockfile.ts` (`acquireLockSync`, `scanStaleLocks`)+ - a sync exclusive-create primitive for the brain write path. Pay+ Memory keeps its async `proper-lockfile` recipe; the brain ships+ its own sync variant to avoid migrating every caller signature.+- `src/core/brain/preference-txn.ts` (`writePreferenceTxn`,+ `BrainCollisionError`, `BRAIN_COLLISION_KIND`, plus three+ expectation factories: `expectRevision`, `noUnsafeShrink`,+ `noDuplicateWriteWithin`). Single chokepoint for every preference+ write. Auto-stamps `_revision` and (on confirmed promotions)+ `_content_hash` for callers that opt in.+- `src/core/brain/content-hash.ts` (`computeContentHash`,+ `verifyContentHash`). sha256 over the trimmed `(principle, scope)`+ pair, neutral when no stored hash is available.+- `_revision: number` and `_content_hash: string` optional fields on+ `BrainPreference`. Both emitted only when the writer supplies them;+ pre-v0.12.0 fixtures and the starter bundle stay byte-identical.+- `src/core/brain/dream-workrun.ts` (`openWorkrun`,+ `scanDanglingWorkruns`, `WORKRUN_PHASE`). One JSONL workrun at+ `Brain/log/dream-runs/<run-id>.jsonl` per mutation-path dream+ invocation; phase markers at `started`, `cluster_complete`,+ `promote_complete`, `retire_complete`, `finalized` (or+ `interrupted` on caught crash). Dry-runs skip workrun emission.+- `DreamRunSummary.gated_retires` carrying `DreamGatedRetireEntry`+ records for retires the destructive-from-confirmed gate skipped.+- `DreamGatedRetireEntry` interface exposing `pref_id`, `topic`,+ `applied_count`, `violated_count`, `threshold`, `attempted_reason`.+- `shouldGateRetireFromConfirmed` exported pure decision helper.+- `retire.confirmed_evidence_min_threshold?: number` optional config+ field on `BrainRetireConfig`. Default-off; when set, the dream+ pass refuses to retire a confirmed (unpinned) pref whose+ `applied_count + violated_count` is below the threshold.+- New `brain_doctor` checks: `content-hash-drift` (warning when the+ stored hash diverges from the recomputed hash of a confirmed+ pref's live principle / scope) and `dangling-workrun` (warning+ for workrun files whose last phase is neither `finalized` nor+ `interrupted`).+- `brain_review_candidates` MCP tool, a read-only projection over+ `dream({ dryRun: true })`. Returns `would_create`,+ `would_promote`, `would_retire`, `would_supersede`,+ `clusters_below_threshold`, `gated_retires`. No state mutates.+- Path helpers `dreamRunsDir(vault)` and `dreamWorkrunPath(vault,+ runId)` in `src/core/brain/paths.ts`.++### Changed++- `dream()` routes its two `writePreference` call sites through+ `writePreferenceTxn`. Promotion writes now produce `_content_hash`+ automatically; refresh writes auto-stamp `_revision` only when the+ proposed bytes would change (idempotent dream reruns stay+ byte-identical with the existing `wouldRewritePreference` shortcut).+- `DreamRunSummary.retired` is filtered to exclude entries that the+ destructive-from-confirmed gate skipped. The public summary now+ matches what actually landed on disk.+## [0.11.0] - 2026-05-26Brain-centric vault layout. The agent now owns one top-level@@ -2884,6 +2955,7 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.+[0.12.0]: https://github.com/itechmeat/open-second-brain/compare/v0.11.0...v0.12.0[0.10.9]: https://github.com/itechmeat/open-second-brain/compare/v0.10.8...v0.10.9[0.10.8]: https://github.com/itechmeat/open-second-brain/compare/v0.10.7...v0.10.8[0.10.7]: https://github.com/itechmeat/open-second-brain/compare/v0.10.6...v0.10.7diff --git a/README.md b/README.mdindex 2dfb1fa8..b2473d74 100644--- a/README.md+++ b/README.md@@ -112,7 +112,7 @@ The capabilities you actually feel day to day:| 9 | Full-text search across the whole vault | `o2b search "<query>" --property type=decision --property status=open` β SQLite + FTS5 plus frontmatter property filters. Faster and more precise than Obsidian's built-in search when you need to grep across thousands of notes. || 10 | Pay Memory β audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |-These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron, cross-project pointers for shared vaults, the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, and an operator dashboard. Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.+These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron, cross-project pointers for shared vaults, the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.## CLIdiff --git a/docs/brainstorm/brain-integrity-suite/cli-output/claude.md b/docs/brainstorm/brain-integrity-suite/cli-output/claude.mdnew file mode 100644index 00000000..bd3c5a50--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/cli-output/claude.md@@ -0,0 +1,35 @@+### Variant 1: Bottom-up primitives, feature-by-feature wiring+- **Approach**: Implement the three shared primitives as small standalone modules (`integrity.ts` for hash + revision compute, `workrun.ts` for JSONL phase log, and a thin re-export of the existing `dream({dryRun:true})` path). Each of the five features then ships as its own commit that imports the primitives and modifies the existing call sites directly β collision checks added inline at `writePreference`, gates added inline at the dream promote/retire steps, workrun calls scattered through `scanBrain` phases, doctor gets a new check appended, `brain_review_candidates` added next to `toolBrainDream`.+- **Trade-offs**:+ - Pro: minimal new abstraction; matches the existing pure-function, `scan β compute β apply` style of the codebase.+ - Pro: each feature has a tight, isolated blast radius β easy to write a failing test per file in `tests/core/brain/<feature>.test.ts`.+ - Pro: lowest review burden per commit; reviewers see exactly which call site changed.+ - Con: integrity logic gets sprinkled across `writePreference` and dream's promote/retire β the same "compare expected vs actual" idea expressed in two places.+ - Con: if a sixth gate is added later, both call sites need parallel edits; drift between the two paths is possible.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Single transactional write-path chokepoint+- **Approach**: Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile` (mirroring `transitionRequest` from `approval.ts:361`): acquire lock β re-read current frontmatter β run all gates as ordered checks (revision/staleness, content-hash drift observer, shrink, duplicate-window, source-lock) β mutate β `writeFrontmatterAtomic` β release. Dream's promote and retire steps call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate become two more `expectations` predicates). Workrun stays a separate concern β a small context object threaded through dream phases β and `brain_review_candidates` is a thin MCP wrapper over the existing `dryRun` path.+- **Trade-offs**:+ - Pro: every collision/gate mode lives in one auditable function; one place to add a future gate, one place to read for invariants.+ - Pro: direct writes via `writePreference` and indirect writes via dream share enforcement guarantees identically β no skew possible.+ - Pro: the lockfile recipe is already proven in-tree; reusing it keeps "no new external deps" trivially true.+ - Con: requires up-front refactor of `writePreference` and all its callers before tests can be made green; first commit is heavier.+ - Con: the txn signature grows (an `expectations` object) β slightly more API surface to learn than the current `(vault, input, options)`.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Validator-chain pipeline+- **Approach**: Model every mutation as a `PreferenceIntent` flowing through `validate β check β apply` stages. Each gate (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite, ShrinkGate, RetireFromConfirmedGate, drift observer) becomes a pure validator returning `ok | block | warn`. Workrun becomes a pipeline observer that records phase transitions; `brain_review_candidates` is the same pipeline with the `apply` stage swapped for `report`. The dream pass is rewritten to feed intents through the pipeline rather than calling `writePreference` directly.+- **Trade-offs**:+ - Pro: maximally extensible; each validator is independently testable as a pure function.+ - Pro: a single mental model β projection, enforcement, and observation all derived from the same chain.+ - Con: introduces a framework the codebase does not have today; conflicts with the "no premature abstraction" stance and the recent v0.11.0 cleanup that retired pre-1.0 shims.+ - Con: reviewers must understand the framework before they can review any feature; the diff balloons and the first commit no longer maps cleanly to one user-visible feature.+ - Con: dream's scan/compute/apply structure has to be inverted into a push-style pipeline β bigger blast radius than the task warrants.+- **Complexity**: large+- **Risk**: medium-high++### Recommended: Variant 2+**Rationale**: Variant 2 centralises every collision and gate on the one place the project already needs to harden β the preference write path β and reuses the proper-lockfile recipe already proven in `transitionRequest`, so it adds no new abstraction the codebase has to learn. Workrun and `brain_review_candidates` stay as small, independent pieces alongside the txn rather than being folded into a unified framework, which keeps the diff legible while still giving the five features a single chokepoint they can share. Variant 1 risks drift between the two write paths and Variant 3 invents a pipeline framework the v0.11.0 line explicitly avoided.diff --git a/docs/brainstorm/brain-integrity-suite/cli-output/prompt.md b/docs/brainstorm/brain-integrity-suite/cli-output/prompt.mdnew file mode 100644index 00000000..8cbc3ded--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/cli-output/prompt.md@@ -0,0 +1,111 @@+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.++# Task++The Open Second Brain ("OSB") codebase needs a **Brain Integrity Suite** that bundles five Brain-side improvements into one PR. All five live inside the same write path (`src/core/brain/preference.ts`, `src/core/brain/dream.ts`, `src/core/brain/policy.ts`, `src/mcp/brain-tools.ts`) and share three primitives that the brainstorm must shape:++1. A revision/hash field on preference frontmatter.+2. A pre-write check that compares expected-vs-actual revision/length/status.+3. A read-only "what would dream do" projection over the existing dream pipeline.++The five user-visible features:++## Feature 1: Content-hash drift detection on confirmed preferences++On promotion to `_status: confirmed`, write `_content_hash: sha256(principle + scope)` into frontmatter. On every read of a confirmed preference (`brain_query`, `brain_search`, `dream` rescan), recompute the hash and compare. Mismatch fires a `drift_detected` event into `Brain/log/<today>.md` (plus JSONL sidecar) and surfaces in `brain_doctor` as a warning. Hand-edits remain legal - the goal is **observability**, not enforcement.++## Feature 2: Structured write-collision detection on preference writes++`writePreference` currently goes through `writeFrontmatterAtomic` (no version check). Four collision modes need typed errors instead of silent last-writer-wins:+- `StaleUpdate` - writer holds an outdated read (compare `_revision` counter or `_last_evidence_at`).+- `UnsafeShrink` - new principle is < N% of existing principle's length (configurable).+- `SourceLock` - signal-lock conflict (a preference is currently being mutated by another in-flight call).+- `DuplicateWrite` - same payload arrives twice from different agents within a short window.++Build on the existing `proper-lockfile`-based `transitionRequest` pattern from `src/core/pay-memory/approval.ts:361` (lock acquire -> re-load inside lock -> verify expected state -> mutate -> writeFrontmatterAtomic -> release).++## Feature 3: Destructive-proof gate on confirmed preferences++Two sub-gates wrapping the dream pass's promotion/retirement logic:+- **Shrink-gate**: if `dream` is about to overwrite a `_status: confirmed` preference's `principle` with text < N% of the existing length, the write is held back and emits a `requires_explicit_replace` quarantine entry instead.+- **Retire-from-confirmed gate**: retiring a `_status: confirmed` preference requires either an explicit operator action (already exists via CLI verb), or an evidence count higher than the default retirement threshold (e.g. 3x). Single-signal retirement of a multi-evidence confirmed pref is rejected.++Both gates emit `brain_note` events when they fire (observable, not blocking-silent).++## Feature 4: Durable workrun checkpoints for dream pass++Today `dream(vault, opts)` runs synchronously, returns `DreamRunSummary`. If the process crashes mid-pass, there is no on-disk trace of progress. Add a JSONL workrun file per dream invocation:+- Path: `Brain/log/dream-runs/<YYYY-MM-DD>-<run-id>.jsonl`+- One line per phase transition. Phases: `started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized | interrupted`.+- On dream startup, scan `dream-runs/` for incomplete files. If found, emit `recovered: <run_id>` event into the regular log and either resume (when safe) or skip (and add a `dangling_workrun` check to `brain_doctor`).++## Feature 5: `brain_review_candidates` - read-only dream-pass projection++A new MCP tool that surfaces what the next `brain_dream` invocation *would* do, without applying anything. Backed by the existing `dream(vault, { dryRun: true })` path (which already exists but is not exposed as a separate tool). Output shape:+```json+{ "would_promote": [], "would_retire": [], "would_supersede": [], "clusters_below_threshold": [] }+```+Pure projection over current inbox + active preferences + retired/. No persistent state added.++## Cross-cutting constraints++- **No Python**. TypeScript with Bun runtime.+- **No new external dependencies** (proper-lockfile is already vendored). sqlite-vec is an optional dep; do not add anything else.+- **Backward compatibility** is NOT required - the codebase explicitly cleared every pre-1.0 shim in v0.11.0 (no public users yet). New frontmatter fields are additive but readers may treat absent-as-default.+- **Atomicity**: every write keeps going through `writeFrontmatterAtomic` from `src/core/vault.ts:151`. New collision detection wraps that, doesn't replace it.+- **All five features must commit on the same feature branch and ship in one PR** (multi-task epic pattern from the feature-release-playbook).+- **No hardcoded human-language strings** for user-facing text. Error names and event codes stay machine-friendly (`StaleUpdate`, `drift_detected`, etc.).+- **TDD-first**: every code change must have a failing-first test in `tests/core/brain/`.++# Project context++**Project:** Open Second Brain - second brain for AI agents using Obsidian-compatible Markdown vaults. TypeScript + Bun. v0.11.0.++**Top files in scope (verified via codegraph):**++| Symbol | Location | Shape |+|---|---|---|+| `dream` | `src/core/brain/dream.ts:191` | `(vault: string, opts: DreamOptions = {}): DreamRunSummary` (sync). Already has `dryRun?: boolean` field. |+| `DreamOptions` | `src/core/brain/dream.ts:134` | Interface; has `dryRun`, `agentName`, etc. |+| `DreamRunSummary` | `src/core/brain/dream.ts:96` | Final summary; has `confirmed`, `retired`, `new_unconfirmed` arrays. |+| `scanBrain` | `src/core/brain/dream.ts:574` | One-pass scan of all topics; no checkpoint emission today. |+| `writePreference` | `src/core/brain/preference.ts:200` | `(vault, input, options): WritePreferenceResult`, sync. Validates fields and calls `writeFrontmatterAtomic`. |+| `preferenceFrontmatter` | `src/core/brain/preference.ts:293` | Builds the FrontmatterMap. Uses `_`-prefix convention for derived fields. |+| `writeFrontmatterAtomic` | `src/core/vault.ts:151` | Atomic file write via temp+rename. The bottom primitive. |+| `transitionRequest` | `src/core/pay-memory/approval.ts:361` | Reference lockfile pattern - `lockfile.lock(target, {retries: {retries:30, factor:1.2, minTimeout:30, maxTimeout:500}, stale:10_000})`, re-load inside lock, mutate, release. |+| `toolBrain*` | `src/mcp/brain-tools.ts` | MCP tool handlers: `(ctx, args) => Promise<Record<string,unknown>>`. Patterns: `toolBrainDream:231`, `toolBrainQuery:479`, `toolBrainNote:340`, `toolBrainDoctor:570`. |+| `brain_note` writer | called via `noteAppend` into `Brain/log/<today>.md` + JSONL sidecar | Existing event-recording surface. |++**Preference frontmatter convention (verified):** Identity fields stay unprefixed (`kind`, `id`, `created_at`, `unconfirmed_until`, `topic`, `principle`, `scope`, `tags`, `aliases`, `supersedes`, `pinned`). Derived/dream-owned fields use `_` prefix (`_status`, `_confirmed_at`, `_evidenced_by`, `_applied_count`, `_violated_count`, `_last_evidence_at`, `_confidence`, `_confidence_value`, `_lifecycle`). New fields from this suite (`_content_hash`, `_revision`) follow the `_` convention.++**Test layout:** `tests/core/brain/<feature>.test.ts` - one file per feature; `bun test` is the harness.++**Conventions from CHANGELOG (v0.10.x - v0.11.0):**+- Pure functions where possible; the dream pipeline is heavy on `scan -> compute -> apply` separation.+- Numeric thresholds configurable via `Brain/_brain.yaml` and surfaced through `loadBrainConfig`.+- Every observable event goes through the log writer (Markdown + JSONL sidecar).+- `brain_doctor` is the operator's invariant check; new checks plug in there.++**Constraints from playbook:**+- One PR per CHANGELOG version (v0.12.0).+- Conventional commits, atomic per feature.+- Mermaid diagrams in PR description must render server-side.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++## Variant N: <short name>++- **Approach**: 2-3 sentences describing the variant.+- **Trade-offs**: bullet list of pros and cons.+- **Complexity**: small | medium | large+- **Risk**: low | medium | high++After the three variants, add exactly one recommendation:++## Recommended: Variant N++**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.++Output nothing outside of these sections.diff --git a/docs/brainstorm/brain-integrity-suite/design.md b/docs/brainstorm/brain-integrity-suite/design.mdnew file mode 100644index 00000000..30de5459--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/design.md@@ -0,0 +1,91 @@+# Brain Integrity Suite - design++**Status:** draft+**Author:** orchestrator (via feature-release-playbook)+**Audience:** implementation++## Problem statement++Open Second Brain's preference write path has three structural gaps. First, confirmed preferences can be silently mutated outside the dream-pass promotion/retirement flow (hand edits, write races, errant agents) with no observable trace. Second, the existing `writePreference` atomic write prevents torn writes but does not prevent stale-update, unsafe-shrink, source-lock, or duplicate-write collisions - the last writer wins silently. Third, the dream pass runs as a single synchronous pipeline with no on-disk progress trace, and there is no read-only way for an operator (or another agent) to inspect what `brain_dream` would do before invoking it.++This release bundles five features that close all three gaps inside one cohesive PR.++## Scope++- **F1: Content-hash drift detection on confirmed preferences.** On promotion, write `_content_hash: sha256(principle + scope)` into frontmatter. Reads recompute and compare; mismatch logs a `drift_detected` event and surfaces in `brain_doctor`.+- **F2: Structured write-collision detection.** Four typed collision modes (`StaleUpdate`, `UnsafeShrink`, `SourceLock`, `DuplicateWrite`) wrapping the write path via a new `writePreferenceTxn` chokepoint that builds on the `proper-lockfile` pattern already proven in `src/core/pay-memory/approval.ts:361`.+- **F3: Destructive-proof gate on confirmed preferences.** Two sub-gates inside the dream pass: shrink-gate (new principle < threshold% of existing length quarantines the candidate); retire-from-confirmed gate (single-signal retirement of a multi-evidence confirmed preference is rejected without operator action or evidence above a higher threshold).+- **F4: Durable workrun checkpoints for dream pass.** Per-invocation JSONL workrun at `Brain/log/dream-runs/<YYYY-MM-DD>-<run-id>.jsonl` with one line per phase transition. Recovery scan on startup; `brain_doctor` check for dangling files.+- **F5: `brain_review_candidates` MCP tool.** Read-only projection over `dream(vault, { dryRun: true })`, exposed as a new MCP tool returning `{ would_promote, would_retire, would_supersede, clusters_below_threshold }`.++## Out of scope++- Per-preference edit-history audit trail (`t_9f452292`) - separate sibling task, not in this PR.+- Cross-vault locking or multi-vault coordination - Pay Memory's lockfile is single-vault.+- Schema migration for existing v0.11.0 preferences - additive fields with absent-as-default reader semantics. No `o2b brain migrate-*` verb.+- Changes to `dedup-hash.ts` (signal/import dedup) - different concern, untouched.++## Chosen approach++**Variant 2: Single transactional write-path chokepoint.**++Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile`: acquire lock on the preference file path, re-read current frontmatter inside the lock, run an ordered chain of `expectations` checks (revision, content-hash drift observer, shrink, duplicate-window, source-lock), mutate via `writeFrontmatterAtomic`, release. Dream's promotion and retirement paths call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate are two predicates plugged into the same expectations chain).++`brain_review_candidates` is a thin MCP wrapper over the already-existing `dream(vault, { dryRun: true })` path. Workrun checkpoints live in a separate small context object threaded through dream phases - they observe transitions but do not own the write semantics.++Variant 1 (bottom-up primitives) was rejected because integrity logic would drift across `writePreference` and dream's promote/retire call sites - two parallel implementations of the same idea. Variant 3 (validator-chain pipeline) was rejected because it invents a framework the codebase explicitly avoids (v0.11.0 removed pre-1.0 shims; the project is the opposite of framework-heavy).++## Design decisions++- **One chokepoint, multiple expectations.** `writePreferenceTxn` is the single function that writes to a preference file. Direct writes from CLI/MCP and indirect writes from dream both go through it; the expectations parameter carries feature-specific predicates (shrink-gate, retire-gate, revision check). This is the SOLID open/closed principle: new gates plug in as expectations without modifying the txn body.+- **Lockfile recipe verbatim from Pay Memory.** Same `retries: { retries: 30, factor: 1.2, minTimeout: 30, maxTimeout: 500 }, stale: 10_000, realpath: false` parameters as `transitionRequest:361`. Single source of truth for the lock semantics; if Pay Memory ever tunes them, the brain mirrors.+- **Hash is opt-in via status.** `_content_hash` is written only when promoting to `confirmed`. Unconfirmed and quarantine preferences do not get the field - they are mutable by design.+- **Drift detection is observation, not enforcement.** A mismatch logs a `drift_detected` event into `Brain/log/<today>.md` (and the JSONL sidecar) and surfaces in `brain_doctor` as a warning. The read still returns the live content; hand-edits remain legal. The operator chooses how to react.+- **Revision counter is monotonic.** `_revision: <integer>` starts at 0 on creation, increments on every txn write. `StaleUpdate` fires when the writer's `expected_revision` does not match the current. Absent field reads as 0 for backward compatibility.+- **Shrink threshold is config-driven, not hardcoded.** New field under `Brain/_brain.yaml`'s existing `confidence` block: `confidence.unsafe_shrink_min_ratio` (default 0.5). Anything below half of the existing principle length triggers UnsafeShrink.+- **Workrun phases are deterministic.** Five phase markers in fixed order: `started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized`. A sixth marker `interrupted` may replace `finalized` on caught crash. Recovery on dream startup is non-resuming: if a workrun is incomplete, log `recovered` (informational), do not auto-resume - the next dream invocation processes the inbox fresh. `brain_doctor` surfaces dangling files as a warning.+- **`brain_review_candidates` is pure projection.** The MCP handler calls `dream(vault, { dryRun: true })` and returns its plan. No new persistent state, no log events, no inbox mutations. Same signature as other read-only tools: `(ctx, args) => Promise<Record<string, unknown>>`.+- **Error class hierarchy.** A new `BrainCollisionError extends Error` with a `kind: 'StaleUpdate' | 'UnsafeShrink' | 'SourceLock' | 'DuplicateWrite'` discriminant. Error names are machine-friendly identifiers; no human-language strings hardcoded.+- **Sync lockfile primitive instead of `proper-lockfile`.** The consultant's Variant 2 recommendation cited the Pay Memory `proper-lockfile` recipe, but Pay Memory is async while the entire brain write path is sync (`writePreference`, `dream`, `moveToRetired`, `writeFrontmatterAtomic`, all callers). `proper-lockfile` v4 has no `lockSync`. Migrating the brain to async would touch 30+ caller files (CLI verbs, MCP handlers, internal call sites) for a feature whose only async-only ingredient is one lock acquire. The right cost is the opposite: write a tiny sync primitive in `src/core/brain/sync-lockfile.ts` that uses `fs.openSync(target + '.lock', 'wx')` for atomic exclusive create. Single-attempt semantics: `EEXIST` raises `BrainCollisionError` with `kind: 'SourceLock'`, no retry loop. Real-world contention in OSB is rare (single operator, single MCP server, dream runs from cron) so the retry/backoff machinery of `proper-lockfile` would be dead code. Pay Memory keeps its async recipe untouched - the two subsystems have different concurrency profiles.++## File changes++**New files:**+- `src/core/brain/preference-txn.ts` - the `writePreferenceTxn` chokepoint, `BrainCollisionError` class, expectations types.+- `src/core/brain/content-hash.ts` - hash computation helper for `principle + scope`.+- `src/core/brain/dream-workrun.ts` - JSONL workrun writer + reader + recovery scan.+- `src/core/brain/review-candidates.ts` - core builder behind `brain_review_candidates` (calls `dream` in dry-run mode and projects the summary).+- `tests/core/brain/preference-txn.test.ts` - txn behaviour, lock semantics.+- `tests/core/brain/content-hash.test.ts` - hash compute + drift detection.+- `tests/core/brain/preference-collision.test.ts` - StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite.+- `tests/core/brain/dream-destructive-gate.test.ts` - shrink-gate + retire-from-confirmed gate.+- `tests/core/brain/dream-workrun.test.ts` - workrun emission, recovery scan, dangling check.+- `tests/core/brain/review-candidates.test.ts` - projection shape, dry-run isolation.+- `tests/mcp/brain-review-candidates.test.ts` - MCP tool wiring.++**Modified files:**+- `src/core/brain/preference.ts` - `writePreference` delegates to `writePreferenceTxn` with empty expectations.+- `src/core/brain/types.ts` - new optional fields on `BrainPreference` (`_revision`, `_content_hash`).+- `src/core/brain/dream.ts` - workrun emission at phase boundaries; promotion/retirement calls go through txn with gate expectations.+- `src/core/brain/policy.ts` - new config fields `confidence.unsafe_shrink_min_ratio` and `retire.confirmed_evidence_multiplier`.+- `src/core/brain/doctor.ts` - new checks for drift, dangling workrun.+- `src/core/brain/query.ts`, `src/core/brain/search.ts` (if separate) - drift verification on read.+- `src/mcp/brain-tools.ts` - new `toolBrainReviewCandidates` handler.+- `src/mcp/tools.ts` - tool registration.+- `src/mcp/instructions.ts` - tool description.+- `CHANGELOG.md` - v0.12.0 entry.+- `README.md` - updated MCP tool table.+- `package.json` - version bump to 0.12.0.+- `scripts/sync-version.ts` and friends pick up the new version automatically.++Estimated diff: ~55-70 files including tests.++## Risks and open questions++- **Lock contention on hot preferences.** Pay Memory's lockfile config (max 30 retries, ~500ms total) is sized for human-operator pace. The dream pass may write many preferences in rapid succession in one run. Verify in implementation that lock acquire latency stays bounded; consider a single in-process mutex sufficient for the same-run case rather than serialising through the filesystem lockfile for each preference.+- **Lock cleanup on crash.** A sync lockfile leaves a `.lock` file on disk if the process aborts between acquire and release. Mitigation: a `process.on('exit', ...)` cleanup hook unlinks every still-held lock during normal exit; for hard crashes (`SIGKILL`, OOM), the next acquire on the same target sees EEXIST and fails with `SourceLock`. The doctor check surfaces stale `.lock` files via `scanStaleLocks(vault)`. Operators can rm them by hand. Pay Memory's `proper-lockfile` has the same class of issue (its `stale: 10_000` timer is for that case); we accept the same hazard with a simpler recovery path.+- **Sync lockfile primitive scope.** New file `src/core/brain/sync-lockfile.ts` (~50 lines). Tests in `tests/core/brain/sync-lockfile.test.ts`. Doctor integration in `src/core/brain/doctor.ts`. Total deltas on the brain write surface: `preference.ts`, `dream.ts`, the new `preference-txn.ts` wrapping both. No caller signatures change.+- **Hash stability across encoding variations.** `sha256(principle + scope)` is sensitive to leading/trailing whitespace and Unicode normalization. Decision: hash the trimmed `principle.trim() + "\n" + (scope ?? "").trim()`, no NFD/NFC normalization (the codebase already does not normalize elsewhere). Document in `content-hash.ts` so a future refactor does not silently invalidate every existing hash.+- **Dream dry-run + workrun interaction.** Dry-run must not write a workrun file - the workrun is part of the durable side-effect surface. Implementation: skip workrun emission when `opts.dryRun === true`.+- **Backward compat for existing v0.11.0 vaults.** All new frontmatter fields are optional; readers fall back to defaults (`_revision` absent reads as 0; missing `_content_hash` on confirmed pref reads as "never hashed yet, hash on next write"). No migration verb.+- **Test data isolation.** Tests need disposable vaults under `os.tmpdir()` per the existing tests/helpers/ pattern; verify `proper-lockfile` cleans up on process exit during a `bun test` interrupt.diff --git a/docs/brainstorm/brain-integrity-suite/plan.md b/docs/brainstorm/brain-integrity-suite/plan.mdnew file mode 100644index 00000000..fdc7cf42--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/plan.md@@ -0,0 +1,79 @@+# Brain Integrity Suite - implementation plan++Seven atomic tasks, all TDD-driven. Each task = failing test first, see fail, minimal code, see green, refactor, atomic conventional commit on `feat/brain-integrity-suite`.++## Tasks++### Task 1: Sync lockfile primitive + `writePreferenceTxn` chokepoint + expectations chain++- **Files**:+ - new `src/core/brain/sync-lockfile.ts` - `acquireLockSync(target): LockHandle`, `LockHandle.release()`, `scanStaleLocks(vault): string[]`, process-exit cleanup hook for held locks. Single-attempt exclusive create via `fs.openSync(target + '.lock', 'wx')`.+ - new `src/core/brain/preference-txn.ts` - `writePreferenceTxn(vault, input, expectations, options): WritePreferenceResult` (sync), `BrainCollisionError extends Error` with `kind` discriminant, `WritePreferenceExpectations` type.+ - modified `src/core/brain/preference.ts` - `writePreference` delegates to `writePreferenceTxn` with an empty expectations array; public signature unchanged.+ - new `tests/core/brain/sync-lockfile.test.ts` - acquire success, EEXIST collision, release, exit-cleanup.+ - new `tests/core/brain/preference-txn.test.ts` - txn flow (lock acquire, re-read, expectations chain, mutate, lock release), expectations chain ordering, error class kind discriminant.+- **Acceptance**: existing `writePreference` tests stay green (no caller signature changes); txn path passes the full lock-acquire / re-read / mutate flow; `BrainCollisionError` exposes `.kind` field with one of four string values; the sync lockfile creates the `.lock` file then removes it on release; `bun test` clean.+- **Depends on**: none (foundation).++### Task 2: `_revision` counter + `_content_hash` frontmatter fields++- **Files**:+ - modified `src/core/brain/types.ts` - add optional `_revision: number`, `_content_hash: string` to `BrainPreference`.+ - modified `src/core/brain/preference.ts` - `WritePreferenceInput` gains optional `revision`, `content_hash`; `preferenceFrontmatter` emits `_revision` (defaults to 0) and `_content_hash` (only when status is `confirmed`).+ - new `src/core/brain/content-hash.ts` - `computeContentHash(principle: string, scope?: string): string`.+ - new `tests/core/brain/content-hash.test.ts` - hash determinism, whitespace handling, scope optional.+ - modified `tests/core/brain/preference.test.ts` or new test file - frontmatter shape with new fields.+- **Acceptance**: `_revision` defaults to 0, increments on each write; `_content_hash` present only on `_status: confirmed`; hash is deterministic for same `(principle, scope)`.+- **Depends on**: Task 1.++### Task 3: Collision-detection expectations (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite)++- **Files**:+ - modified `src/core/brain/preference-txn.ts` - four expectations: `expectRevision(n)`, `noUnsafeShrink(minRatio)`, `sourceLockGuard`, `noDuplicateWrite(window)`.+ - modified `src/core/brain/policy.ts` - config fields `confidence.unsafe_shrink_min_ratio` (default 0.5) and `retire.confirmed_evidence_multiplier` (default 3).+ - new `tests/core/brain/preference-collision.test.ts` - one describe-block per collision kind, each with red-then-green case.+- **Acceptance**: each collision mode raises `BrainCollisionError` with correct `kind`; lock acquisition timeout maps to `SourceLock`; config defaults loadable via `loadBrainConfig`.+- **Depends on**: Task 1, Task 2.++### Task 4: Drift detection on confirmed-preference reads++- **Files**:+ - modified `src/core/brain/content-hash.ts` - `verifyContentHash(pref): { ok: boolean; observed?: string; expected?: string }`.+ - modified `src/core/brain/query.ts` (or wherever `brain_query` reads preferences) - on `_status: confirmed` reads, call `verifyContentHash`, emit `drift_detected` event via existing log writer when mismatch.+ - modified `src/core/brain/doctor.ts` - new `BrainDoctorCheck` for drift summary.+ - new event code constant `BRAIN_EVENT.driftDetected` in the same place other event codes live.+ - new `tests/core/brain/content-hash-drift.test.ts` - mutate principle on disk, read, assert event emitted.+- **Acceptance**: hand-editing a confirmed preference's `principle` triggers exactly one `drift_detected` event per read (not per byte); `brain_doctor` surfaces a count of drifted preferences; mismatch does not block the read.+- **Depends on**: Task 2.++### Task 5: Destructive-proof gates in dream pass++- **Files**:+ - modified `src/core/brain/dream.ts` - promotion path passes `noUnsafeShrink` expectation when target is `_status: confirmed`; retirement path passes `requireEvidenceCountAbove(threshold)` when source is `_status: confirmed`.+ - modified `src/core/brain/types.ts` - new `DreamQuarantinedEntry` reason codes `unsafe_shrink`, `retire_evidence_below_threshold`.+ - new `tests/core/brain/dream-destructive-gate.test.ts` - feed dream a single-signal retirement against multi-evidence confirmed pref; assert quarantine entry returned, pref unchanged on disk.+- **Acceptance**: dream's `DreamRunSummary.retired` does not include a confirmed pref when evidence count is below multiplier; `quarantined` array carries the rejected attempt with the relevant `failed_gates` code; existing dream tests stay green.+- **Depends on**: Task 3.++### Task 6: Durable workrun checkpoints for dream pass++- **Files**:+ - new `src/core/brain/dream-workrun.ts` - `openWorkrun(vault, runId): WorkrunHandle`, `WorkrunHandle.checkpoint(phase)`, `WorkrunHandle.finalize()`, `WorkrunHandle.interrupt()`, `scanDanglingWorkruns(vault): string[]`.+ - modified `src/core/brain/dream.ts` - phase markers at the four transition points; skipped when `opts.dryRun === true`.+ - modified `src/core/brain/paths.ts` - `dreamRunsDir(vault)`, `dreamWorkrunPath(vault, runId)` path helpers.+ - modified `src/core/brain/doctor.ts` - check `scanDanglingWorkruns` and surface as warning.+ - new `tests/core/brain/dream-workrun.test.ts` - emission ordering, recovery scan, dry-run skip.+- **Acceptance**: a full dream pass writes exactly one workrun file with five JSONL lines (`started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized`); a crashed run (test simulates) leaves a workrun without `finalized` and is picked up by the doctor check.+- **Depends on**: none structurally, but Task 5 should land first so dream's promote/retire phases are stable.++### Task 7: `brain_review_candidates` MCP tool++- **Files**:+ - new `src/core/brain/review-candidates.ts` - `buildReviewCandidates(vault): ReviewCandidatesReport`, internally calls `dream(vault, { dryRun: true })` and projects.+ - modified `src/mcp/brain-tools.ts` - `toolBrainReviewCandidates(ctx, args)` handler matching the existing tool signature.+ - modified `src/mcp/tools.ts` - tool registration entry.+ - modified `src/mcp/instructions.ts` - tool description for the agent-facing surface.+ - new `tests/core/brain/review-candidates.test.ts` - shape and dry-run isolation (no files mutated).+ - new `tests/mcp/brain-review-candidates.test.ts` - MCP tool wiring + arg shape.+- **Acceptance**: the tool returns `{ would_promote, would_retire, would_supersede, clusters_below_threshold }`; invoking it twice in a row produces the same result without writing any new files; the tool is discoverable through the MCP server's tool list.+- **Depends on**: Task 6 (so the workrun does not fire on dry-run is exercised together).diff --git a/docs/brainstorm/brain-integrity-suite/pr-body.md b/docs/brainstorm/brain-integrity-suite/pr-body.mdnew file mode 100644index 00000000..13fcf1e9--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/pr-body.md@@ -0,0 +1,69 @@+## Summary++Adds the **Brain Integrity Suite** to the Open Second Brain preference write path: every confirmed preference now carries a content hash, every dream write goes through a typed-collision chokepoint, and every dream invocation leaves a durable on-disk workrun. The destructive-from-confirmed retire gate and the read-only `brain_review_candidates` MCP tool round out the bundle. Eight atomic features, one cohesive PR.++## Why this matters++```mermaid+flowchart LR+ A[Agent or operator<br/>edits a preference] --> B{Where does the write land?}+ B -->|pre-v0.12.0| C[writeFrontmatterAtomic]+ C --> D[On-disk file<br/>no audit, no gates]+ D --> E[Silent drift / race / shrink]++ B -->|v0.12.0| F[writePreferenceTxn]+ F --> G[Lock acquire<br/>sync .lock file]+ G --> H[Expectations chain<br/>StaleUpdate / UnsafeShrink / DuplicateWrite]+ H --> I[Smart defaults<br/>_revision bump + _content_hash on confirmed]+ I --> J[writeFrontmatterAtomic]+ J --> K[Durable workrun JSONL<br/>+ doctor surfaces]+ K --> L[Inspectable history]+```++The pre-v0.12.0 write path could not tell a legitimate edit apart from a write race or a silent shrink; the v0.12.0 path surfaces every category as a typed error or a doctor warning.++## Concrete benefits++- **Drift becomes observable.** Hand-edits to a confirmed preference produce a `content-hash-drift` warning in `brain_doctor` instead of going silent.+- **Crash forensics.** A dream pass killed mid-execution leaves a `dream-runs/<run-id>.jsonl` with phases up to the killpoint. The next pass scans for dangling workruns and surfaces them.+- **Destructive-proof retires.** When `retire.confirmed_evidence_min_threshold` is set, the dream pass refuses to retire a confirmed (unpinned) preference whose accumulated evidence is below the floor. Skipped retires surface in `DreamRunSummary.gated_retires`.+- **Pre-flight visibility.** `brain_review_candidates` lets an agent or operator ask "what would the next dream pass do?" without touching disk.+- **Single chokepoint for future gates.** New collision modes plug into `writePreferenceTxn` as expectation functions; no parallel patches across `preference.ts` and `dream.ts`.++## What ships++| Module | Role |+|---|---|+| `src/core/brain/sync-lockfile.ts` | Single-attempt sync exclusive-create primitive. EEXIST -> `Error.code = 'ELOCKED'`. |+| `src/core/brain/preference-txn.ts` | `writePreferenceTxn` chokepoint, `BrainCollisionError` with four typed `kind` discriminants, three expectation factories. |+| `src/core/brain/content-hash.ts` | `computeContentHash` and `verifyContentHash` over the canonical trimmed `(principle, scope)` pair. |+| `src/core/brain/dream-workrun.ts` | JSONL workrun writer + scanner. Recovery is non-resuming; the doctor surfaces dangling files. |+| `src/core/brain/review-candidates.ts` | Read-only projection over `dream({ dryRun: true })`. |+| `src/core/brain/dream.ts` | Promotion + refresh writes routed through the txn; destructive-from-confirmed retire gate wired into the retires loop. |+| `src/core/brain/doctor.ts` | New checks: `content-hash-drift` and `dangling-workrun`. |+| `src/mcp/brain-tools.ts` + `instructions.ts` | New MCP tool `brain_review_candidates`. |++## Test plan++- [x] `bun test` - 2379 pass / 0 fail / 5937 expects across the full suite (including 64 new tests across 11 new test files).+- [x] `bun run typecheck` - clean.+- [x] `bun run sync-version:check` - canonical 0.12.0 across seven manifests.+- [x] Integration coverage: a fresh dream pass that promotes an unconfirmed pref to confirmed writes `_content_hash` matching the canonical hash on disk (`tests/core/brain/dream-content-hash-promotion.test.ts`).+- [x] Idempotency invariant: a second dream pass on the same vault state produces byte-identical preference files (`tests/core/brain.dream.test.ts:512`).+- [x] Starter bundle no-op: `dream` on the curated starter at a fixed `--now` returns `changed: false` (`tests/core/brain/starter.test.ts:158`).+- [x] Doctor drift: writing a confirmed pref with a stale `_content_hash` surfaces exactly one `content-hash-drift` warning (`tests/core/brain/doctor-drift.test.ts`).+- [x] Workrun lifecycle: phases recorded in order, dry-run skips emission, `scanDanglingWorkruns` returns paths of unfinalised files (`tests/core/brain/dream-workrun.test.ts`).+- [x] Destructive-gate pure decision: nine branches of `shouldGateRetireFromConfirmed` covered (`tests/core/brain/dream-destructive-gate.test.ts`).+- [x] MCP wiring: `brain_review_candidates` registered in `BRAIN_TOOLS`, returns six fields all empty on a fresh vault (`tests/mcp/brain-review-candidates.test.ts`). Tool count 31 -> 32.++## Design and decision trail++- `docs/brainstorm/brain-integrity-suite/design.md` - the chosen approach and rejected alternatives.+- `docs/brainstorm/brain-integrity-suite/plan.md` - the per-task implementation plan.+- `docs/brainstorm/brain-integrity-suite/variants.md` - audit trail of the three architectural variants the consultant produced.++## Notes++- Default-off rollout for the destructive-from-confirmed gate (`retire.confirmed_evidence_min_threshold`) keeps every pre-v0.12.0 dream behaviour byte-identical until the operator opts in via `Brain/_brain.yaml`.+- `proper-lockfile` remains a runtime dep for Pay Memory; the brain write path uses its own sync primitive to avoid migrating every caller signature to async. Decision rationale captured in the design doc.+- The `drift-detected` log event kind was planned but is not emitted in v0.12.0; the doctor warning is the surface. The enum entry is intentionally absent rather than promised-and-unmet.diff --git a/docs/brainstorm/brain-integrity-suite/variants.md b/docs/brainstorm/brain-integrity-suite/variants.mdnew file mode 100644index 00000000..02663721--- /dev/null+++ b/docs/brainstorm/brain-integrity-suite/variants.md@@ -0,0 +1,59 @@+# Brain Integrity Suite - brainstorm audit trail++This file records the architectural variants the consultant produced for the Brain Integrity Suite and the orchestrator's final rationale. It is intentionally verbose - future readers should see the options that lost and why.++The prompt fed to the consultant is at `cli-output/prompt.md`. The raw consultant transcript is at `cli-output/claude.md`.++## Consultant: Claude Code++Invocation: `claude -p "$(cat cli-output/prompt.md)" 2>&1 | tee cli-output/claude.md`++### Variant 1: Bottom-up primitives, feature-by-feature wiring++- **Approach**: Implement the three shared primitives as small standalone modules (`integrity.ts` for hash + revision compute, `workrun.ts` for JSONL phase log, and a thin re-export of the existing `dream({dryRun:true})` path). Each of the five features then ships as its own commit that imports the primitives and modifies the existing call sites directly - collision checks added inline at `writePreference`, gates added inline at the dream promote/retire steps, workrun calls scattered through `scanBrain` phases, doctor gets a new check appended, `brain_review_candidates` added next to `toolBrainDream`.+- **Trade-offs**:+ - Pro: minimal new abstraction; matches the existing pure-function, `scan to compute to apply` style of the codebase.+ - Pro: each feature has a tight, isolated blast radius - easy to write a failing test per file in `tests/core/brain/<feature>.test.ts`.+ - Pro: lowest review burden per commit; reviewers see exactly which call site changed.+ - Con: integrity logic gets sprinkled across `writePreference` and dream's promote/retire - the same "compare expected vs actual" idea expressed in two places.+ - Con: if a sixth gate is added later, both call sites need parallel edits; drift between the two paths is possible.+- **Complexity**: medium+- **Risk**: low++### Variant 2: Single transactional write-path chokepoint++- **Approach**: Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile` (mirroring `transitionRequest` from `approval.ts:361`): acquire lock then re-read current frontmatter then run all gates as ordered checks (revision/staleness, content-hash drift observer, shrink, duplicate-window, source-lock) then mutate then `writeFrontmatterAtomic` then release. Dream's promote and retire steps call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate become two more `expectations` predicates). Workrun stays a separate concern - a small context object threaded through dream phases - and `brain_review_candidates` is a thin MCP wrapper over the existing `dryRun` path.+- **Trade-offs**:+ - Pro: every collision/gate mode lives in one auditable function; one place to add a future gate, one place to read for invariants.+ - Pro: direct writes via `writePreference` and indirect writes via dream share enforcement guarantees identically - no skew possible.+ - Pro: the lockfile recipe is already proven in-tree; reusing it keeps "no new external deps" trivially true.+ - Con: requires up-front refactor of `writePreference` and all its callers before tests can be made green; first commit is heavier.+ - Con: the txn signature grows (an `expectations` object) - slightly more API surface to learn than the current `(vault, input, options)`.+- **Complexity**: medium+- **Risk**: medium++### Variant 3: Validator-chain pipeline++- **Approach**: Model every mutation as a `PreferenceIntent` flowing through `validate to check to apply` stages. Each gate (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite, ShrinkGate, RetireFromConfirmedGate, drift observer) becomes a pure validator returning `ok | block | warn`. Workrun becomes a pipeline observer that records phase transitions; `brain_review_candidates` is the same pipeline with the `apply` stage swapped for `report`. The dream pass is rewritten to feed intents through the pipeline rather than calling `writePreference` directly.+- **Trade-offs**:+ - Pro: maximally extensible; each validator is independently testable as a pure function.+ - Pro: a single mental model - projection, enforcement, and observation all derived from the same chain.+ - Con: introduces a framework the codebase does not have today; conflicts with the "no premature abstraction" stance and the recent v0.11.0 cleanup that retired pre-1.0 shims.+ - Con: reviewers must understand the framework before they can review any feature; the diff balloons and the first commit no longer maps cleanly to one user-visible feature.+ - Con: dream's scan/compute/apply structure has to be inverted into a push-style pipeline - bigger blast radius than the task warrants.+- **Complexity**: large+- **Risk**: medium-high++### Consultant recommendation: Variant 2++> Variant 2 centralises every collision and gate on the one place the project already needs to harden - the preference write path - and reuses the proper-lockfile recipe already proven in `transitionRequest`, so it adds no new abstraction the codebase has to learn. Workrun and `brain_review_candidates` stay as small, independent pieces alongside the txn rather than being folded into a unified framework, which keeps the diff legible while still giving the five features a single chokepoint they can share. Variant 1 risks drift between the two write paths and Variant 3 invents a pipeline framework the v0.11.0 line explicitly avoided.++## Orchestrator decision: Variant 2 (agree with consultant)++The consultant's rationale matches the project context. Reinforcing reasons specific to OSB:++1. **DRY across two write paths.** CLI/MCP writes (via `writePreference`) and dream-internal writes (via `dream.ts`'s promotion/retirement) are today two parallel paths through the same primitive (`writeFrontmatterAtomic`). Variant 1 would entrench the parallelism; Variant 2 collapses both into one chokepoint. The project's own CHANGELOG entry for v0.11.0 explicitly removed dual-shape parsers and lift-only overlays - the spirit of "one path, no overlay" pushes toward Variant 2.+2. **`proper-lockfile` is already a runtime dep.** Adding Variant 2's lockfile gate costs zero new dependencies. The Pay Memory reference implementation (`approval.ts:361`) is a 30-line recipe to copy.+3. **Workrun and review-candidates do not benefit from the txn abstraction.** They are pure observers / pure projections. Variant 3's "everything through the validator chain" would force them into the wrong shape.++Variant 3 is explicitly rejected on cultural grounds: this project removed framework-y abstractions in v0.11.0; reintroducing one for five features that fit naturally as a chokepoint plus two helpers is the opposite direction.diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 8af74050..ae45a58b 100644--- a/openclaw.plugin.json+++ b/openclaw.plugin.json@@ -2,7 +2,7 @@"id": "open-second-brain","name": "Open Second Brain","description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",- "version": "0.11.0",+ "version": "0.12.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex c6c0d2a9..7caa9ac7 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.11.0",+ "version": "0.12.0","type": "module","private": false,"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",diff --git a/plugin.yaml b/plugin.yamlindex c2efaf38..67a9c180 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.11.0"+version: "0.12.0"description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex ee83dcef..f6623579 100644--- a/plugins/codex/.codex-plugin/plugin.json+++ b/plugins/codex/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.11.0",+ "version": "0.12.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex bd7e2b65..ce053274 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.11.0"+version: "0.12.0"description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/pyproject.toml b/pyproject.tomlindex e75ab3f4..aa28018c 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"# CLI entry points (those moved to `package.json` `bin`).[project]name = "open-second-brain"-version = "0.11.0"+version = "0.12.0"description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."readme = "README.md"requires-python = ">=3.11"diff --git a/src/core/brain/content-hash.ts b/src/core/brain/content-hash.tsnew file mode 100644index 00000000..17937cfd--- /dev/null+++ b/src/core/brain/content-hash.ts@@ -0,0 +1,83 @@+/**+ * Content-hash helper for confirmed preferences.+ *+ * On promotion to `_status: confirmed`, the dream pass writes+ * `_content_hash: sha256(principle + scope)` into the frontmatter via+ * {@link computeContentHash}. Every subsequent read of a confirmed+ * preference recomputes the hash; {@link verifyContentHash} compares+ * stored vs. recomputed and tells the caller whether the on-disk+ * content has drifted away from what dream last sealed.+ *+ * Hand-editing a confirmed preference stays legal - drift detection+ * is observability, not enforcement. A mismatch surfaces as a+ * `drift_detected` event in `Brain/log/<today>.md` and as a counter+ * in `brain_doctor`. The read returns the live content unchanged.+ *+ * Normalisation rules baked into the digest input:+ * - principle and scope are trimmed of leading/trailing whitespace+ * - absent / empty / undefined scope normalises to the empty string+ *+ * Both rules keep the hash stable across the frontmatter round-trip+ * and across the writer's "skip emit for blank scope" semantic.+ */++import { createHash } from "node:crypto";++const SEPARATOR = "\n";++/**+ * Compute the canonical content hash for a preference's+ * (principle, scope) pair. Returns a 64-char lowercase hex sha256.+ */+export function computeContentHash(principle: string, scope?: string): string {+ const normalisedPrinciple = (principle ?? "").trim();+ const normalisedScope = (scope ?? "").trim();+ const payload = `${normalisedPrinciple}${SEPARATOR}${normalisedScope}`;+ return createHash("sha256").update(payload, "utf8").digest("hex");+}++/**+ * Input shape for {@link verifyContentHash}. A pared-down view of+ * {@link BrainPreference} that takes only the three fields the hash+ * compares - so the helper can be called either with a parsed+ * `BrainPreference` (with the matching field names) or with a fresh+ * `{principle, scope, content_hash}` synthesised from elsewhere.+ */+export interface ContentHashInput {+ readonly principle: string;+ readonly scope?: string;+ readonly content_hash?: string;+}++export interface ContentHashVerification {+ /**+ * `true` when stored hash matches recomputed, OR when the stored+ * hash is absent (legacy preference written before this field+ * existed - we cannot detect drift, so we do not lie about it).+ */+ readonly ok: boolean;+ /** Recomputed hash; undefined when the input had no stored hash to compare against. */+ readonly expected?: string;+ /** Stored hash from frontmatter; undefined when the input had none. */+ readonly observed?: string;+}++/**+ * Compare the stored `_content_hash` against the recomputed hash of+ * the live (principle, scope) pair. When the stored value is absent+ * the result is neutral (`ok: true`, no expected/observed) - the+ * caller MUST NOT log a drift event in that case.+ */+export function verifyContentHash(+ input: ContentHashInput,+): ContentHashVerification {+ if (!input.content_hash) {+ return { ok: true };+ }+ const expected = computeContentHash(input.principle, input.scope);+ return {+ ok: expected === input.content_hash,+ expected,+ observed: input.content_hash,+ };+}diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.tsindex 78e09c44..2d01d985 100644--- a/src/core/brain/doctor.ts+++ b/src/core/brain/doctor.ts@@ -42,6 +42,8 @@ import { join } from "node:path";import { extractWikilinks, listVaultBasenames, parseFrontmatter } from "../vault.ts";import { resolveVaultScope } from "../vault-scope/index.ts";import { buildBacklinkIndex } from "./backlinks.ts";+import { verifyContentHash } from "./content-hash.ts";+import { scanDanglingWorkruns } from "./dream-workrun.ts";import { parseLogDay } from "./log.ts";import {BRAIN_CONFIG_SUPPORTED_VERSIONS,@@ -282,6 +284,21 @@ export function runDoctor(checkPinnedWithoutRecentEvidence(prefRecords, issues, cfg, now);} catch { /* doctor never throws */ }}+ // v0.12.0 Brain Integrity Suite: surface preferences whose live+ // (principle, scope) does not hash to the value stored in+ // `_content_hash`. Hand-edits remain legal; the warning makes them+ // observable.+ try {+ checkContentHashDrift(prefRecords, issues);+ } catch { /* doctor never throws */ }+ // v0.12.0 Brain Integrity Suite: surface every dream workrun file+ // whose last phase is neither `finalized` nor `interrupted`. A+ // dangling workrun is forensic evidence that a previous dream+ // invocation crashed - the operator can inspect the file to see+ // how far the run got.+ try {+ checkDanglingWorkruns(vault, issues);+ } catch { /* doctor never throws */ }try {checkMalformedEvidenceRange(logRecords, issues);} catch { /* doctor never throws */ }@@ -910,6 +927,69 @@ function checkPinnedWithoutRecentEvidence(}}+/**+ * `content-hash-drift` (v0.12.0, Brain Integrity Suite): walks every+ * confirmed preference, recomputes the content hash from the live+ * `(principle, scope)`, and surfaces a warning whenever the stored+ * `_content_hash` no longer matches. Legacy preferences without a+ * stored hash are silent - drift detection is opt-in via the+ * promotion-time hash write.+ *+ * Hand-edits stay legal: this is observability, not enforcement. The+ * operator sees the divergence and decides whether to re-promote the+ * preference (which writes a fresh hash) or accept the drift.+ */+function checkContentHashDrift(+ prefs: ReadonlyArray<PreferenceRecord>,+ issues: DoctorIssue[],+): void {+ for (const { path, pref } of prefs) {+ if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;+ if (!pref.content_hash) continue;+ const v = verifyContentHash({+ principle: pref.principle,+ scope: pref.scope,+ content_hash: pref.content_hash,+ });+ if (!v.ok) {+ issues.push({+ severity: "warning",+ code: "content-hash-drift",+ path,+ message:+ `content-hash drift on ${pref.id}: stored ${v.observed} ` ++ `does not match recomputed ${v.expected}`,+ });+ }+ }+}++/**+ * `dangling-workrun` (v0.12.0, Brain Integrity Suite): surfaces every+ * dream-pass workrun JSONL whose last event is neither `finalized`+ * nor `interrupted`. A non-empty result means at least one previous+ * dream invocation died before it could declare a terminal phase,+ * usually because the host process was killed mid-run. The next+ * dream pass starts fresh - this check is purely observational so+ * the operator notices the failed run.+ */+function checkDanglingWorkruns(+ vault: string,+ issues: DoctorIssue[],+): void {+ for (const path of scanDanglingWorkruns(vault)) {+ issues.push({+ severity: "warning",+ code: "dangling-workrun",+ path,+ message:+ `dream-pass workrun did not reach a terminal phase: ${path}. ` ++ "A previous dream run was likely killed mid-execution; " ++ "subsequent dream invocations will continue normally.",+ });+ }+}+/*** `malformed-evidence-range`: walks every `apply-evidence` event,* runs the artifact wikilink through {@link parseArtifactRef}, anddiff --git a/src/core/brain/dream-workrun.ts b/src/core/brain/dream-workrun.tsnew file mode 100644index 00000000..2d289994--- /dev/null+++ b/src/core/brain/dream-workrun.ts@@ -0,0 +1,155 @@+/**+ * Durable workrun checkpoints for the dream pass (Brain Integrity+ * Suite Feature 4).+ *+ * Each dream invocation opens a JSONL workrun file under+ * `Brain/log/dream-runs/<run-id>.jsonl` and records one line per+ * phase transition (`started`, `cluster_complete`, `promote_complete`,+ * `retire_complete`, `finalized` | `interrupted`). A crash mid-pass+ * leaves an inspectable trail; the next invocation calls+ * {@link scanDanglingWorkruns} on startup to find any run that did+ * not reach `finalized` / `interrupted`. Recovery is non-resuming -+ * the next dream pass processes the inbox fresh; the dangling file+ * serves as forensic evidence, not a resumable state machine.+ *+ * Dry-run never opens a workrun: dryRun must not mutate disk.+ *+ * Writes use `appendFileSync` on the same file. The OS guarantees+ * `O_APPEND` is atomic for small writes (under PIPE_BUF, 4096 bytes+ * on Linux); each JSONL line is ~120 bytes so a partial write would+ * be deeply pathological. We do not fsync per phase - a crash that+ * loses the last phase line is acceptable (the file is still flagged+ * dangling on the next scan).+ */++import {+ appendFileSync,+ existsSync,+ lstatSync,+ mkdirSync,+ readFileSync,+ readdirSync,+} from "node:fs";+import { dirname, join } from "node:path";++import {+ dreamRunsDir,+ dreamWorkrunPath,+} from "./paths.ts";++/**+ * Canonical phase identifiers. Five forward-progress phases plus the+ * sticky `interrupted` terminal. The dream pass emits them in the+ * order declared; readers MUST tolerate unknown future phases.+ */+export const WORKRUN_PHASE = Object.freeze({+ started: "started",+ clusterComplete: "cluster_complete",+ promoteComplete: "promote_complete",+ retireComplete: "retire_complete",+ finalized: "finalized",+ interrupted: "interrupted",+} as const);++export type WorkrunPhase =+ (typeof WORKRUN_PHASE)[keyof typeof WORKRUN_PHASE];++export interface WorkrunHandle {+ /** Path of the underlying JSONL file. */+ readonly path: string;+ /** Append one checkpoint line. Silent no-op after finalize/interrupt. */+ checkpoint(phase: WorkrunPhase, payload?: Record<string, unknown>): void;+ /** Append the terminal `finalized` line. Idempotent. */+ finalize(): void;+ /** Append a terminal `interrupted` line with optional reason. Idempotent. */+ interrupt(reason?: string): void;+}++/**+ * Open a workrun for `runId`, immediately writing the `started`+ * phase. Creates the workrun directory on demand.+ */+export function openWorkrun(vault: string, runId: string): WorkrunHandle {+ const path = dreamWorkrunPath(vault, runId);+ mkdirSync(dirname(path), { recursive: true });+ let closed = false;+ const append = (phase: WorkrunPhase, extra: Record<string, unknown> = {}): void => {+ const line = JSON.stringify({+ phase,+ at: new Date().toISOString(),+ run_id: runId,+ ...extra,+ }) + "\n";+ appendFileSync(path, line, "utf8");+ };+ append(WORKRUN_PHASE.started);+ return {+ path,+ checkpoint(phase: WorkrunPhase, payload: Record<string, unknown> = {}): void {+ if (closed) return;+ append(phase, payload);+ },+ finalize(): void {+ if (closed) return;+ closed = true;+ append(WORKRUN_PHASE.finalized);+ },+ interrupt(reason?: string): void {+ if (closed) return;+ closed = true;+ append(+ WORKRUN_PHASE.interrupted,+ reason !== undefined ? { reason } : {},+ );+ },+ };+}++/**+ * Walk `Brain/log/dream-runs/` and return the paths of every workrun+ * whose last event is neither `finalized` nor `interrupted`. A+ * corrupt / unparseable file is treated as dangling so the operator+ * sees it.+ */+export function scanDanglingWorkruns(vault: string): string[] {+ const dir = dreamRunsDir(vault);+ if (!existsSync(dir)) return [];+ const out: string[] = [];+ for (const name of readdirSync(dir)) {+ if (!name.endsWith(".jsonl")) continue;+ const path = join(dir, name);+ // Skip non-regular files (a directory named `*.jsonl` would+ // otherwise be reported as dangling on the very first readFileSync+ // failure). lstat ignores symlinks the same way.+ try {+ if (!lstatSync(path).isFile()) continue;+ } catch {+ continue;+ }+ try {+ const text = readFileSync(path, "utf8");+ const lines = text.split("\n").filter((l) => l.trim().length > 0);+ if (lines.length === 0) {+ out.push(path);+ continue;+ }+ const last = lines[lines.length - 1]!;+ let parsed: { phase?: unknown };+ try {+ parsed = JSON.parse(last) as { phase?: unknown };+ } catch {+ out.push(path);+ continue;+ }+ if (+ parsed.phase !== WORKRUN_PHASE.finalized &&+ parsed.phase !== WORKRUN_PHASE.interrupted+ ) {+ out.push(path);+ }+ } catch {+ out.push(path);+ }+ }+ return out;+}diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.tsindex 10af4c13..13759494 100644--- a/src/core/brain/dream.ts+++ b/src/core/brain/dream.ts@@ -39,7 +39,13 @@ import { basename, join } from "node:path";import { parseFrontmatter } from "../vault.ts";import { regenerateActiveQuiet } from "./active.ts";+import {+ openWorkrun,+ WORKRUN_PHASE,+ type WorkrunHandle,+} from "./dream-workrun.ts";import { collectEvidenceForSlug } from "./evidence.ts";+import { writePreferenceTxn } from "./preference-txn.ts";import {appendLogEvent,parseLogDay,@@ -49,7 +55,6 @@ import {moveToRetired,parsePreference,wouldRewritePreference,- writePreference,} from "./preference.ts";import { parseSignal } from "./signal.ts";import { isPinned } from "./pin.ts";@@ -134,6 +139,25 @@ export interface DreamQuarantinedEntry {readonly failed_gates: ReadonlyArray<string>;}+/**+ * Brain Integrity Suite (v0.12.0). Entry for a retire that the dream+ * pass declined because `retire.confirmed_evidence_min_threshold` was+ * set and the source preference's accumulated evidence count fell+ * below it. The pref stays in `preferences/`; the operator can lift+ * the gate by raising the evidence count, lowering the threshold, or+ * running `o2b brain reject` explicitly.+ */+export interface DreamGatedRetireEntry {+ readonly pref_id: string;+ readonly topic: string;+ readonly applied_count: number;+ readonly violated_count: number;+ /** Configured threshold the pref's evidence count fell below. */+ readonly threshold: number;+ /** The retire reason the plan computed before the gate fired. */+ readonly attempted_reason: BrainRetiredReason;+}+export interface DreamRunSummary {/** `dream-YYYY-MM-DD-HHMMSS`. */readonly run_id: string;@@ -177,6 +201,13 @@ export interface DreamRunSummary {* match pre-v0.10.16 behaviour.*/readonly quarantined: ReadonlyArray<DreamQuarantinedEntry>;+ /**+ * Brain Integrity Suite (v0.12.0). Retires the dream pass planned+ * but declined to execute because the source preference's evidence+ * count fell below `retire.confirmed_evidence_min_threshold`. Empty+ * when the config field is absent (the default).+ */+ readonly gated_retires: ReadonlyArray<DreamGatedRetireEntry>;/** Snapshot file (absent on a no-op run). */readonly snapshot_path?: string;/** Log file the run summary landed in (absent on a no-op run). */@@ -332,6 +363,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {warnings: Object.freeze([...warnings]),uncertain: Object.freeze([] as ReadonlyArray<DreamUncertainEntry>),quarantined: Object.freeze([...plan.quarantined]),+ gated_retires: Object.freeze([] as ReadonlyArray<DreamGatedRetireEntry>),...(dryRun ? { dry_run: true } : {}),} satisfies DreamRunSummary);}@@ -358,13 +390,32 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {// 5. Emit log entries (noted-redundant, retain-pinned,// skip-corrupted-frontmatter, dream summary).const moved: string[] = [];+ // v0.12.0 Brain Integrity Suite: declined retires accumulate here.+ // Always declared (even when no gate is configured) so the eventual+ // DreamRunSummary.gated_retires field is consistently an array.+ const gatedRetires: DreamGatedRetireEntry[] = [];++ // v0.12.0 Brain Integrity Suite: durable workrun for the dream pass.+ // Opened lazily on the mutation path (no workrun on dry-run or+ // no-op early-return). The handle is null until the exec branch+ // claims it; `finally` finalises if non-null.+ let workrun: WorkrunHandle | null = null;+ if (!dryRun) {+ workrun = openWorkrun(vault, runId);+ workrun.checkpoint(WORKRUN_PHASE.clusterComplete);+ }if (!dryRun) {for (const np of plan.newUnconfirmed) {// Fresh pref has no apply-evidence yet; recentApplied/recentViolated// start empty and stay so until the next dream pass after the// first `brain_apply_evidence` event.- writePreference(+ // v0.12.0 Brain Integrity Suite: route every dream-pass write+ // through writePreferenceTxn so _revision auto-stamps and+ // _content_hash lands automatically on confirmed promotions.+ // Empty expectations array - dream's plan-time logic has+ // already decided to proceed; the txn just owns the bookkeeping.+ writePreferenceTxn(vault,{slug: np.slug,@@ -386,6 +437,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {...(np.scope ? { scope: np.scope } : {}),...(np.supersedes ? { supersedes: np.supersedes } : {}),},+ [],{ overwrite: false },);}@@ -398,7 +450,9 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {const ev = collectEvidenceForSlug(vault, update.slug, {sinceIso: update.created_at,});- writePreference(+ // Same txn route as the newUnconfirmed loop: auto-stamps+ // _revision (existing+1) and _content_hash on confirmed status.+ writePreferenceTxn(vault,{slug: update.slug,@@ -419,6 +473,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {recentViolated: ev.violated,...(update.scope ? { scope: update.scope } : {}),},+ [],{ overwrite: true },);}@@ -426,6 +481,31 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {for (const r of plan.retires) {const fromPath = preferencePath(vault, r.slug);if (!existsSync(fromPath)) continue;+ // v0.12.0 Brain Integrity Suite: destructive-from-confirmed gate.+ // When the operator has set retire.confirmed_evidence_min_threshold,+ // refuse to retire a confirmed (unpinned) pref whose accumulated+ // evidence count is below the configured floor. Operator-initiated+ // retires bypass.+ const gateThreshold = cfg.retire.confirmed_evidence_min_threshold;+ if (gateThreshold !== undefined && gateThreshold > 0) {+ try {+ const existing = parsePreference(fromPath);+ if (shouldGateRetireFromConfirmed(existing, r.reason, gateThreshold)) {+ gatedRetires.push({+ pref_id: existing.id,+ topic: existing.topic,+ applied_count: existing.applied_count,+ violated_count: existing.violated_count,+ threshold: gateThreshold,+ attempted_reason: r.reason,+ });+ continue;+ }+ } catch {+ // Parse failure - fall through to the normal retire path+ // (moveToRetired will surface the error through stderr below).+ }+ }try {moveToRetired(vault, fromPath, r.reason, {now,@@ -463,6 +543,24 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {for (const sig of plan.signalsToMove.values()) moved.push(sig.id);}+ // v0.12.0 Brain Integrity Suite: mark promote + retire phases. The+ // dream.ts execution loop runs promote (writePreference) then retire+ // (moveToRetired) sequentially; one checkpoint covers both+ // mutations so the workrun stays compact yet recovery-meaningful.+ if (workrun !== null) {+ workrun.checkpoint(WORKRUN_PHASE.promoteComplete);+ workrun.checkpoint(WORKRUN_PHASE.retireComplete);+ }++ // v0.12.0 Brain Integrity Suite: build the gated-slug set once so the+ // log body and the DreamRunSummary stay consistent β both views must+ // exclude retires the destructive-from-confirmed gate skipped, or+ // the next dream pass would parse a `pref-foo` log claiming the+ // pref was retired while the file is still in `preferences/`.+ const gatedSlugs = new Set(+ gatedRetires.map((g) => g.pref_id.replace(/^pref-/, "")),+ );+// Emit log entries: skip-corrupted-frontmatter first (chronological// sense: corruption was detected during planning), then per-topic// events (noted-redundant), then run summary last.@@ -547,10 +645,12 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {?? "",}),);- const retiredEntries = plan.retires.map(- (r) =>- `${renderPrefLink({ id: `ret-${r.slug}`, principle: r.principle })} (${r.reason})`,- );+ const retiredEntries = plan.retires+ .filter((r) => !gatedSlugs.has(r.slug))+ .map(+ (r) =>+ `${renderPrefLink({ id: `ret-${r.slug}`, principle: r.principle })} (${r.reason})`,+ );const summaryBody: Record<string, string | ReadonlyArray<string>> = {run_id: runId,};@@ -610,12 +710,20 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {regenerateActiveQuiet(vault, { now });}+ // v0.12.0 Brain Integrity Suite: finalise the durable workrun+ // immediately before constructing the summary. Any crash building+ // the summary leaves the workrun dangling for the next pass to+ // spot. `workrun` is null on dry-run / pre-mutation paths.+ workrun?.finalize();+return Object.freeze({run_id: runId,changed: true,new_unconfirmed: plan.newUnconfirmed.map((p) => `pref-${p.slug}`),confirmed: Array.from(refresh.confirmed.values()).map((s) => `pref-${s}`),- retired: plan.retires.map((r) => ({ id: `ret-${r.slug}`, reason: r.reason })),+ retired: plan.retires+ .filter((r) => !gatedSlugs.has(r.slug))+ .map((r) => ({ id: `ret-${r.slug}`, reason: r.reason })),contradictions: Array.from(plan.contradictionTopics),moved_to_processed: moved,suppressed: plan.signalsSuppressed.map((s) =>@@ -624,6 +732,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {warnings: Object.freeze([...warnings]),uncertain: Object.freeze([] as ReadonlyArray<DreamUncertainEntry>),quarantined: Object.freeze([...plan.quarantined]),+ gated_retires: Object.freeze([...gatedRetires]),...(snapshotPathStr ? { snapshot_path: snapshotPathStr } : {}),...(dryRun? { dry_run: true }@@ -631,6 +740,30 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {} satisfies DreamRunSummary);}+/**+ * Brain Integrity Suite (v0.12.0). Pure decision function for the+ * destructive-from-confirmed gate. Exported so the gate logic can be+ * unit-tested without driving a full dream run.+ *+ * Returns `true` when the candidate retire MUST be held back. The+ * caller is responsible for recording a {@link DreamGatedRetireEntry}+ * and skipping the actual `moveToRetired` call.+ */+export function shouldGateRetireFromConfirmed(+ existing: BrainPreference,+ reason: BrainRetiredReason,+ threshold: number | undefined,+): boolean {+ if (threshold === undefined || threshold <= 0) return false;+ if (reason === BRAIN_RETIRED_REASON.userRejected) return false;+ if (reason === BRAIN_RETIRED_REASON.mergedInto) return false;+ if (existing.status !== BRAIN_PREFERENCE_STATUS.confirmed) return false;+ if (existing.pinned) return false;+ const evidenceCount =+ (existing.applied_count ?? 0) + (existing.violated_count ?? 0);+ return evidenceCount < threshold;+}+// ----- Scan ---------------------------------------------------------------function scanBrain(vault: string): ScanResult {@@ -1492,6 +1625,24 @@ function planRefresh(...prospective,recentApplied: ev2.applied,recentViolated: ev2.violated,+ // v0.12.0 Brain Integrity Suite: feed the existing+ // _revision and _content_hash into the pre-flight render+ // so the byte comparison matches the writePreferenceTxn+ // no-op semantic. Otherwise a refreshed pref written by a+ // prior pass (with _revision: N stamped) would look like+ // "needs rewrite" against a prospective render that omits+ // those fields, flipping changed=false runs into spurious+ // updates.+ // parsePreference defaults absent _revision to 0; treat 0+ // the same as "absent" for the pre-flight render so the+ // bytes-compare matches existing legacy starter files that+ // never had the field on disk.+ ...(rec.pref.revision !== undefined && rec.pref.revision > 0+ ? { revision: rec.pref.revision }+ : {}),+ ...(rec.pref.content_hash !== undefined+ ? { content_hash: rec.pref.content_hash }+ : {}),})) {// Counters and body both unchanged β true no-op for this pref.diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.tsindex e565f1a7..3ed62421 100644--- a/src/core/brain/paths.ts+++ b/src/core/brain/paths.ts@@ -186,6 +186,26 @@ export function logJsonlPath(vault: string, date: string): string {return ensureInsideVault(join(brainDirs(vault).log, `${d}.jsonl`), vault);}+/**+ * Brain Integrity Suite (v0.12.0). Workrun directory used by the+ * durable dream-pass checkpoint surface: `Brain/log/dream-runs/`.+ * Lives under the log dir so backups already include it.+ */+export function dreamRunsDir(vault: string): string {+ return join(brainDirs(vault).log, "dream-runs");+}++/**+ * Brain Integrity Suite (v0.12.0). Durable workrun JSONL for a+ * single dream invocation: `Brain/log/dream-runs/<run-id>.jsonl`.+ * The run id is validated through {@link validateRunId} so it stays+ * inside the canonical directory.+ */+export function dreamWorkrunPath(vault: string, runId: string): string {+ const id = validateRunId(runId);+ return ensureInsideVault(join(dreamRunsDir(vault), `${id}.jsonl`), vault);+}+/** Snapshots directory: `Brain/.snapshots/`. */export function snapshotsDir(vault: string): string {return brainDirs(vault).snapshots;diff --git a/src/core/brain/preference-txn.ts b/src/core/brain/preference-txn.tsnew file mode 100644index 00000000..14fa27a5--- /dev/null+++ b/src/core/brain/preference-txn.ts@@ -0,0 +1,285 @@+/**+ * `writePreferenceTxn` - single chokepoint for every preference write.+ *+ * Direct writes via {@link writePreference} and indirect writes via the+ * dream pass (promotion / retirement) both flow through this function.+ * That gives the brain integrity suite one place to bolt on every+ * collision check and gate (drift, stale-update, unsafe-shrink,+ * destructive replacement, ...) without sprinkling parallel checks+ * across `preference.ts` and `dream.ts`.+ *+ * Shape:+ *+ * 1. Compute target path from `input.slug`.+ * 2. Acquire the sync lockfile (`<path>.lock`). EEXIST -> `SourceLock`+ * collision error (typed).+ * 3. Re-read the existing preference inside the lock, if the file+ * already exists. The expectations chain sees this snapshot+ * verbatim - any check that depends on "current vs. proposed"+ * reads it from `ctx.existing`.+ * 4. Run the expectations chain in order. The first one that throws+ * `BrainCollisionError` aborts the txn; subsequent expectations+ * do not run.+ * 5. Delegate the write to {@link writePreference} (which handles+ * validation, frontmatter rendering, content-equality shortcut,+ * and the atomic write itself).+ * 6. Release the lock in a `finally` block so the lock is freed+ * regardless of whether the write or an expectation threw.+ */++import { existsSync } from "node:fs";++import { computeContentHash } from "./content-hash.ts";+import {+ preferencePath,+ validateSlug,+} from "./paths.ts";+import {+ parsePreference,+ writePreference,+ wouldRewritePreference,+ type WritePreferenceInput,+ type WritePreferenceOptions,+ type WritePreferenceResult,+} from "./preference.ts";+import { acquireLockSync } from "./sync-lockfile.ts";+import {+ BRAIN_PREFERENCE_STATUS,+ type BrainPreference,+} from "./types.ts";++/**+ * Machine-friendly discriminants for the four collision modes covered+ * by the brain integrity suite. No human-language strings: the names+ * surface as `.kind` on {@link BrainCollisionError} and as event codes+ * in `Brain/log/`. Languages-of-output stay out of the rule itself.+ */+export const BRAIN_COLLISION_KIND = Object.freeze({+ staleUpdate: "StaleUpdate",+ unsafeShrink: "UnsafeShrink",+ sourceLock: "SourceLock",+ duplicateWrite: "DuplicateWrite",+} as const);++export type BrainCollisionKind =+ (typeof BRAIN_COLLISION_KIND)[keyof typeof BRAIN_COLLISION_KIND];++/**+ * Typed error surfaced by every txn collision mode. `kind` is the+ * machine-readable discriminant; the message carries human prose only+ * for log/console rendering.+ */+export class BrainCollisionError extends Error {+ readonly kind: BrainCollisionKind;++ constructor(kind: BrainCollisionKind, message: string) {+ super(message);+ this.name = "BrainCollisionError";+ this.kind = kind;+ }+}++/**+ * Context passed to every expectation. Carries the resolved path, the+ * existing preference (if any), and the proposed input. Expectations+ * must be pure relative to the txn's own state - they can throw+ * {@link BrainCollisionError} but must not mutate `ctx`.+ */+export interface WritePreferenceContext {+ readonly vault: string;+ readonly path: string;+ readonly existing: BrainPreference | null;+ readonly input: WritePreferenceInput;+}++/**+ * One expectation in the chain. Synchronous, runs inside the lock+ * after the existing preference (if any) has been re-read. Throws+ * {@link BrainCollisionError} to abort the write; returning normally+ * signals "ok, keep going".+ */+export type WritePreferenceExpectation = (+ ctx: WritePreferenceContext,+) => void;++/**+ * Write a preference under an exclusive sync lock, running the+ * expectations chain before the mutation. {@link writePreference}'s+ * own validation + rendering + atomic-write still runs - the txn just+ * gates it.+ *+ * Callers without collision checks pass an empty expectations array;+ * the txn then behaves identically to `writePreference(vault, input,+ * options)` aside from the lock acquire/release pair (which is cheap+ * when uncontended).+ */+export function writePreferenceTxn(+ vault: string,+ input: WritePreferenceInput,+ expectations: ReadonlyArray<WritePreferenceExpectation>,+ options: WritePreferenceOptions = {},+): WritePreferenceResult {+ const slug = validateSlug(input.slug);+ const path = preferencePath(vault, slug);++ let handle: ReturnType<typeof acquireLockSync>;+ try {+ handle = acquireLockSync(path);+ } catch (err) {+ const e = err as NodeJS.ErrnoException;+ if (e.code === "ELOCKED") {+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.sourceLock,+ `preference write blocked by active lock: ${path}`,+ );+ }+ throw err;+ }++ try {+ const existing = existsSync(path) ? parsePreference(path) : null;+ const ctx: WritePreferenceContext = Object.freeze({+ vault,+ path,+ existing,+ input,+ });+ for (const expectation of expectations) {+ expectation(ctx);+ }+ // Brain Integrity Suite smart defaults (v0.12.0). The txn owns+ // two pieces of bookkeeping for callers that opt in:+ //+ // - `_content_hash` lands automatically on promotion to+ // `confirmed` so the doctor's drift check has something to+ // compare against. Skipped when the caller supplies a hash+ // of their own.+ // - `_revision` is a monotonic write counter that increments+ // ONLY when the proposed content would actually change the+ // on-disk bytes. A dream-pass no-op rerun must stay+ // byte-identical, so the txn pre-renders the would-be write+ // with the existing revision and bumps only when+ // `wouldRewritePreference` says the file would change.+ //+ // Callers that bypass the txn keep pre-v0.12.0 semantics.+ const autoHash =+ input.content_hash === undefined+ && input.status === BRAIN_PREFERENCE_STATUS.confirmed+ ? { content_hash: computeContentHash(input.principle, input.scope) }+ : {};+ const candidate: WritePreferenceInput = {+ ...input,+ ...autoHash,+ revision: input.revision ?? (existing?.revision ?? 0),+ };+ const willChange =+ input.revision !== undefined+ || existing === null+ || wouldRewritePreference(vault, candidate);+ const inputWithDefaults: WritePreferenceInput = willChange+ ? {+ ...candidate,+ revision: input.revision ?? ((existing?.revision ?? 0) + 1),+ }+ : candidate;+ return writePreference(vault, inputWithDefaults, options);+ } finally {+ handle.release();+ }+}++// ----- Expectation factories -----------------------------------------------+//+// Each factory returns a {@link WritePreferenceExpectation} ready to be+// dropped into the txn's expectations array. Callers compose them+// declaratively at the call site; the txn runs them in order under the+// lock, before delegating to {@link writePreference}.++/**+ * StaleUpdate gate. The writer must declare which revision it read;+ * the txn rejects the write if the on-disk revision has moved.+ *+ * Treats a missing on-disk `_revision` field as 0 - the absent-as-zero+ * convention from {@link BrainPreference.revision}'s reader.+ */+export function expectRevision(+ expected: number,+): WritePreferenceExpectation {+ return (ctx) => {+ const current = ctx.existing?.revision ?? 0;+ if (current !== expected) {+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.staleUpdate,+ `stale update: expected revision ${expected}, found ${current} (path=${ctx.path})`,+ );+ }+ };+}++/**+ * UnsafeShrink gate. The new principle's length must stay at or above+ * `minRatio * existingPrinciple.length`. A first-time write (no+ * existing preference) is always allowed.+ *+ * `minRatio` should be a value in `(0, 1]`. The dream pass passes+ * `cfg.confidence.unsafe_shrink_min_ratio` here when promoting or+ * refreshing a confirmed preference.+ */+export function noUnsafeShrink(minRatio: number): WritePreferenceExpectation {+ if (!Number.isFinite(minRatio) || minRatio <= 0 || minRatio > 1) {+ throw new RangeError(+ `noUnsafeShrink(minRatio) expects a finite value in (0, 1]; got ${String(minRatio)}`,+ );+ }+ return (ctx) => {+ if (!ctx.existing) return;+ const existingLen = ctx.existing.principle.length;+ if (existingLen <= 0) return;+ const newLen = ctx.input.principle.length;+ const ratio = newLen / existingLen;+ if (ratio < minRatio) {+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.unsafeShrink,+ `unsafe shrink: new principle ${newLen} chars is below ${minRatio} * ${existingLen} (ratio=${ratio.toFixed(3)})`,+ );+ }+ };+}++/**+ * DuplicateWrite gate. Triggers when the proposed content's+ * {@link computeContentHash} matches the existing `content_hash`+ * AND the existing `last_evidence_at` is within `windowMs` of `now()`.+ *+ * Use case: an agent re-fires a `dream` refresh for the same pref+ * while a previous write is still settling. The gate stays silent on+ * legacy preferences (no `content_hash`) so backfills are never+ * mis-classified as duplicates.+ *+ * `now` is injectable so tests do not depend on wall-clock.+ */+export function noDuplicateWriteWithin(+ windowMs: number,+ now: () => Date = () => new Date(),+): WritePreferenceExpectation {+ return (ctx) => {+ const existing = ctx.existing;+ if (!existing) return;+ const existingHash = existing.content_hash;+ if (!existingHash) return;+ const proposedHash = computeContentHash(+ ctx.input.principle,+ ctx.input.scope,+ );+ if (existingHash !== proposedHash) return;+ const lastEv = existing.last_evidence_at;+ if (!lastEv) return;+ const ageMs = now().getTime() - new Date(lastEv).getTime();+ if (ageMs >= 0 && ageMs < windowMs) {+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.duplicateWrite,+ `duplicate write: identical content hash within ${windowMs}ms window (age=${ageMs}ms)`,+ );+ }+ };+}diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.tsindex f0c46249..a109863a 100644--- a/src/core/brain/preference.ts+++ b/src/core/brain/preference.ts@@ -128,6 +128,21 @@ export interface WritePreferenceInput {*/readonly tier?: PageTier;readonly pinned?: boolean;+ /**+ * Brain Integrity Suite (v0.12.0). Optional monotonic write counter+ * persisted as `_revision`. `writePreferenceTxn` auto-stamps the+ * next value when callers omit. Direct `writePreference` callers+ * that omit the field skip the emission entirely - legacy fixtures+ * stay byte-identical (the reader treats absent as `0`).+ */+ readonly revision?: number;+ /**+ * Brain Integrity Suite (v0.12.0). Optional sha256 of the canonical+ * `(principle, scope)` pair persisted as `_content_hash`. Dream+ * supplies on promotion to `confirmed`; emitted verbatim when+ * supplied, omitted otherwise.+ */+ readonly content_hash?: string;readonly supersedes?: string;readonly aliases?: ReadonlyArray<string>;/** Optional extra tags merged after the canonical set. */@@ -334,6 +349,12 @@ function preferenceFrontmatter(_confidence_value: confidenceValueField,pinned,};+ // Brain Integrity Suite additive fields. Both follow the+ // `_lifecycle` precedent: emit only when the caller supplies a+ // value so legacy fixtures and the starter bundle stay+ // byte-identical with absent-as-default reader semantics.+ if (input.revision !== undefined) metadata["_revision"] = input.revision;+ if (input.content_hash) metadata["_content_hash"] = input.content_hash;if (input.scope?.trim()) metadata["scope"] = input.scope.trim();if (input.supersedes?.trim()) metadata["supersedes"] = input.supersedes.trim();if (input.aliases && input.aliases.length > 0) {@@ -459,6 +480,8 @@ export const DERIVED_FIELDS: ReadonlyArray<string> = Object.freeze(["evidenced_by","contradicted_by","lifecycle",+ "revision",+ "content_hash",]);/**@@ -553,6 +576,10 @@ export function parsePreference(path: string): BrainPreference {confidence: parseConfidence(meta, path),confidence_value: parseConfidenceValue(meta, path),pinned: parsePinned(meta),+ revision: optionalNumber(meta, "revision", 0),+ ...(optionalScalarString(meta, "content_hash") !== undefined+ ? { content_hash: optionalScalarString(meta, "content_hash") }+ : {}),...(optionalScalarString(meta, "scope") !== undefined? { scope: optionalScalarString(meta, "scope") }: {}),diff --git a/src/core/brain/review-candidates.ts b/src/core/brain/review-candidates.tsnew file mode 100644index 00000000..b991f410--- /dev/null+++ b/src/core/brain/review-candidates.ts@@ -0,0 +1,111 @@+/**+ * Brain Integrity Suite (v0.12.0) - `brain_review_candidates`.+ *+ * Read-only projection over what the next `dream` invocation would+ * do. Calls `dream(vault, { dryRun: true })` and reshapes the+ * summary into a focused agent-facing report. No persistent state+ * is mutated; the underlying dry-run dream pass also skips the+ * workrun emission.+ *+ * The shape is intentionally narrow - just the fields an operator or+ * agent needs to decide "should I do anything before the dream pass+ * runs?". Callers that want the full DreamRunSummary should call+ * `brain_dream` with `dry_run: true` directly.+ */++import { dream } from "./dream.ts";+import { BRAIN_RETIRED_REASON, type BrainRetiredReason } from "./types.ts";++export interface ReviewCandidatesReport {+ /** `pref-<slug>` ids that the dream pass would create new. */+ readonly would_create: ReadonlyArray<string>;+ /** `pref-<slug>` ids transitioning unconfirmed -> confirmed. */+ readonly would_promote: ReadonlyArray<string>;+ /** Retire entries (id + reason). */+ readonly would_retire: ReadonlyArray<{+ readonly id: string;+ readonly reason: BrainRetiredReason;+ }>;+ /** Subset of `would_retire` whose reason is `superseded-by-context`. */+ readonly would_supersede: ReadonlyArray<{+ readonly id: string;+ readonly reason: BrainRetiredReason;+ }>;+ /**+ * Signal clusters held back by the self-approval guardrail. Mirror+ * of `DreamRunSummary.quarantined` plus a one-shot+ * `failed_gates` list.+ */+ readonly clusters_below_threshold: ReadonlyArray<{+ readonly topic: string;+ readonly signal_count: number;+ readonly distinct_agents: number;+ readonly age_days: number;+ readonly failed_gates: ReadonlyArray<string>;+ }>;+ /**+ * Retires the destructive-from-confirmed gate would skip. Mirror+ * of `DreamRunSummary.gated_retires`.+ */+ readonly gated_retires: ReadonlyArray<{+ readonly pref_id: string;+ readonly topic: string;+ readonly applied_count: number;+ readonly violated_count: number;+ readonly threshold: number;+ readonly attempted_reason: BrainRetiredReason;+ }>;+}++export interface BuildReviewCandidatesOptions {+ /** Wall clock for the underlying dream pass. */+ readonly now?: Date;+}++export function buildReviewCandidates(+ vault: string,+ opts: BuildReviewCandidatesOptions = {},+): ReviewCandidatesReport {+ const summary = dream(vault, {+ dryRun: true,+ ...(opts.now ? { now: opts.now } : {}),+ });++ return Object.freeze({+ would_create: Object.freeze([...summary.new_unconfirmed]),+ would_promote: Object.freeze([...summary.confirmed]),+ would_retire: Object.freeze(+ summary.retired.map((r) =>+ Object.freeze({ id: r.id, reason: r.reason }),+ ),+ ),+ would_supersede: Object.freeze(+ summary.retired+ .filter((r) => r.reason === BRAIN_RETIRED_REASON.supersededByContext)+ .map((r) => Object.freeze({ id: r.id, reason: r.reason })),+ ),+ clusters_below_threshold: Object.freeze(+ summary.quarantined.map((q) =>+ Object.freeze({+ topic: q.topic,+ signal_count: q.signal_count,+ distinct_agents: q.distinct_agents,+ age_days: q.age_days,+ failed_gates: Object.freeze([...q.failed_gates]),+ }),+ ),+ ),+ gated_retires: Object.freeze(+ summary.gated_retires.map((g) =>+ Object.freeze({+ pref_id: g.pref_id,+ topic: g.topic,+ applied_count: g.applied_count,+ violated_count: g.violated_count,+ threshold: g.threshold,+ attempted_reason: g.attempted_reason,+ }),+ ),+ ),+ } satisfies ReviewCandidatesReport);+}diff --git a/src/core/brain/sync-lockfile.ts b/src/core/brain/sync-lockfile.tsnew file mode 100644index 00000000..e6636d5c--- /dev/null+++ b/src/core/brain/sync-lockfile.ts@@ -0,0 +1,168 @@+/**+ * Synchronous lockfile primitive for the brain write path.+ *+ * Pay Memory locks through `proper-lockfile` (async). The brain write+ * path is sync end-to-end (`writePreference`, `dream`, `moveToRetired`,+ * `writeFrontmatterAtomic`) and migrating it to async would touch every+ * caller signature for one async-only ingredient. Instead, this module+ * provides a tiny single-attempt sync lock built on `fs.openSync(target+ * + '.lock', 'wx')`. EEXIST surfaces as `Error` with+ * `.code === 'ELOCKED'`; the brain txn layer maps that to a+ * `BrainCollisionError({ kind: 'SourceLock' })`.+ *+ * No retry/backoff. Contention in OSB is rare (single operator, single+ * MCP server, dream runs from cron). When it does happen, we prefer a+ * loud typed error over a silent retry-then-still-fail loop.+ *+ * Stale-lock recovery: on normal process exit the cleanup hook unlinks+ * any still-held locks. On hard crash (SIGKILL, OOM) the `.lock` file+ * stays on disk and the next acquire fails with ELOCKED; the brain+ * doctor surfaces these via {@link scanStaleLocks} so an operator can+ * remove them by hand.+ */++import {+ closeSync,+ mkdirSync,+ openSync,+ readdirSync,+ unlinkSync,+ writeSync,+} from "node:fs";+import { dirname, join } from "node:path";++export interface LockHandle {+ /** Filesystem path to the underlying `.lock` file. */+ readonly path: string;+ /** Release the lock. Idempotent: a second call is a no-op. */+ release(): void;+}++const LOCK_SUFFIX = ".lock";++// Held locks, tracked at module scope so the exit hook can clean up.+const heldLocks = new Set<string>();+let exitHookInstalled = false;++function ensureExitHook(): void {+ if (exitHookInstalled) return;+ exitHookInstalled = true;+ process.on("exit", () => {+ for (const lockPath of heldLocks) {+ try {+ unlinkSync(lockPath);+ } catch {+ // best-effort; the next acquire will see ELOCKED and surface it+ }+ }+ heldLocks.clear();+ });+}++/**+ * Acquire an exclusive lock for `target`. Returns a handle whose+ * {@link LockHandle.release} method unlinks the underlying `.lock`+ * file. Throws `Error & { code: 'ELOCKED' }` if the lock is already+ * held.+ *+ * The target file itself does NOT need to exist - first-time writes+ * acquire the lock before creating the target. The parent directory+ * is created on demand.+ */+export function acquireLockSync(target: string): LockHandle {+ ensureExitHook();+ const lockPath = target + LOCK_SUFFIX;+ mkdirSync(dirname(lockPath), { recursive: true });++ let fd: number;+ try {+ fd = openSync(lockPath, "wx", 0o644);+ } catch (err) {+ const e = err as NodeJS.ErrnoException;+ if (e.code === "EEXIST") {+ const collision: NodeJS.ErrnoException = new Error(+ `lock busy: ${lockPath}`,+ );+ collision.code = "ELOCKED";+ collision.path = lockPath;+ throw collision;+ }+ throw err;+ }++ // Stamp pid + timestamp into the lock body. The contents are+ // purely diagnostic - the doctor surface reads them when reporting+ // stale locks. Failure to write is non-fatal: the lock semantics+ // come from the exclusive create, not from the body.+ try {+ const stamp = Buffer.from(+ `${process.pid}\n${new Date().toISOString()}\n`,+ "utf8",+ );+ writeSync(fd, stamp, 0, stamp.byteLength);+ } catch {+ // ignore; diagnostic-only payload+ } finally {+ try {+ closeSync(fd);+ } catch {+ // ignore+ }+ }++ heldLocks.add(lockPath);+ let released = false;+ return {+ path: lockPath,+ release(): void {+ if (released) return;+ released = true;+ heldLocks.delete(lockPath);+ try {+ unlinkSync(lockPath);+ } catch {+ // already gone (race with exit hook or manual cleanup); ignore+ }+ },+ };+}++/**+ * Walk `root` recursively and return every `.lock` file path. Used by+ * `brain_doctor` to surface stale locks left behind by a crashed+ * process.+ */+export function scanStaleLocks(root: string): string[] {+ const out: string[] = [];+ walkLocks(root, out);+ return out;+}++function walkLocks(dir: string, out: string[]): void {+ let entries;+ try {+ entries = readdirSync(dir, { withFileTypes: true });+ } catch {+ return;+ }+ for (const entry of entries) {+ const full = join(dir, entry.name);+ if (entry.isDirectory()) {+ walkLocks(full, out);+ continue;+ }+ if (!entry.isFile()) continue;+ if (entry.name.endsWith(LOCK_SUFFIX)) {+ out.push(full);+ }+ }+}++/**+ * Test-only: clear the held-locks tracking set without unlinking. Used+ * to keep cross-test state from leaking when a test deliberately+ * leaves a lock on disk for the next test to discover.+ */+export function _resetHeldLocksForTests(): void {+ heldLocks.clear();+}diff --git a/src/core/brain/types.ts b/src/core/brain/types.tsindex 97152b45..a9ca9ded 100644--- a/src/core/brain/types.ts+++ b/src/core/brain/types.ts@@ -330,6 +330,22 @@ export interface BrainPreference {* to `false`.*/readonly pinned: boolean;+ /**+ * Brain Integrity Suite: monotonic write counter (v0.12.0). Starts+ * at 0; incremented by `writePreferenceTxn` on every mutation.+ * `StaleUpdate` collision fires when a writer's `expected_revision`+ * does not match this on-disk value. Absent on pre-v0.12.0 files;+ * readers must tolerate `undefined` and coerce to `0`.+ */+ readonly revision?: number;+ /**+ * Brain Integrity Suite: sha256 of the canonical `(principle,+ * scope)` pair (v0.12.0). Written on promotion to `confirmed`;+ * absent for unconfirmed and quarantine preferences. Recomputed on+ * read by {@link verifyContentHash}; a mismatch surfaces as a+ * `drift_detected` event in the log.+ */+ readonly content_hash?: string;/** Optional wikilink to a retired pref this one replaces. */readonly supersedes?: string;readonly aliases?: ReadonlyArray<string>;@@ -631,6 +647,18 @@ export interface BrainDreamConfig {export interface BrainRetireConfig {/** Days without evidence after which a confirmed pref retires. */readonly stale_evidence_days: number;+ /**+ * Brain Integrity Suite (v0.12.0). Destructive-from-confirmed gate.+ * When set to a positive integer, the dream pass refuses to retire+ * a confirmed (and unpinned) preference whose accumulated+ * `applied_count + violated_count` is below this threshold. Skipped+ * retires surface in `DreamRunSummary.gated_retires` and stay in+ * `preferences/`. Operator-initiated retires (`user-rejected`,+ * `merged-into`) are never gated. `undefined` (default) preserves+ * pre-v0.12.0 behaviour where any retire that the plan computed+ * lands on disk.+ */+ readonly confirmed_evidence_min_threshold?: number;}export interface BrainConfidenceConfig {diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex 932b56f5..c1ebfcc7 100644--- a/src/mcp/brain-tools.ts+++ b/src/mcp/brain-tools.ts@@ -76,6 +76,7 @@ import {type DigestFormat,} from "../core/brain/digest.ts";import { dream } from "../core/brain/dream.ts";+import { buildReviewCandidates } from "../core/brain/review-candidates.ts";import { runDoctor } from "../core/brain/doctor.ts";import { buildOperatorSummary } from "../core/brain/trust/operator-summary.ts";import { BRAIN_ROLES } from "../core/brain/trust/role.ts";@@ -299,6 +300,45 @@ async function toolBrainDream(};}+// ----- brain_review_candidates --------------------------------------------++async function toolBrainReviewCandidates(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const nowDate = coerceIsoDate(args, "now");+ const report = buildReviewCandidates(ctx.vault, {+ ...(nowDate ? { now: nowDate } : {}),+ });+ return {+ would_create: [...report.would_create],+ would_promote: [...report.would_promote],+ would_retire: report.would_retire.map((r) => ({+ id: r.id,+ reason: r.reason,+ })),+ would_supersede: report.would_supersede.map((r) => ({+ id: r.id,+ reason: r.reason,+ })),+ clusters_below_threshold: report.clusters_below_threshold.map((c) => ({+ topic: c.topic,+ signal_count: c.signal_count,+ distinct_agents: c.distinct_agents,+ age_days: c.age_days,+ failed_gates: [...c.failed_gates],+ })),+ gated_retires: report.gated_retires.map((g) => ({+ pref_id: g.pref_id,+ topic: g.topic,+ applied_count: g.applied_count,+ violated_count: g.violated_count,+ threshold: g.threshold,+ attempted_reason: g.attempted_reason,+ })),+ };+}+// ----- brain_apply_evidence ------------------------------------------------async function toolBrainApplyEvidence(@@ -1428,6 +1468,23 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([},handler: toolBrainDream,},+ {+ name: "brain_review_candidates",+ description:+ "Read-only preview of what the next `brain_dream` invocation would do. Returns `would_create`, `would_promote`, `would_retire`, `would_supersede`, `clusters_below_threshold`, and `gated_retires` without mutating any files. Useful for agents that want to be deliberate before triggering the learning pass, or for operators inspecting the dream pass intent.",+ inputSchema: {+ type: "object",+ properties: {+ now: {+ type: "string",+ description:+ "Optional ISO-8601 timestamp used as the wall clock for the dry-run (testing / replay).",+ },+ },+ additionalProperties: false,+ },+ handler: toolBrainReviewCandidates,+ },{name: "brain_apply_evidence",description:diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.tsindex 6b5723e4..587dff8b 100644--- a/src/mcp/instructions.ts+++ b/src/mcp/instructions.ts@@ -78,6 +78,12 @@ export function buildInstructions(opts: BuildInstructionsOpts | string): string" - brain_dream β runs the deterministic learning pass " +"(clusters signals, promotes preferences, retires stale rules). " +"Usually scheduled via cron, not invoked interactively.\n" ++ " - brain_review_candidates β read-only preview of what the " ++ "next `brain_dream` invocation would do. Returns `would_create`, " ++ "`would_promote`, `would_retire`, `would_supersede`, " ++ "`clusters_below_threshold`, and `gated_retires` without mutating " ++ "any files. Use it when you want to be deliberate before " ++ "triggering the learning pass.\n" +" - brain_digest β read-only summary of the last activity " +"window. Default format is Markdown; pass `format: \"json\"` for " +"programmatic use.\n" +diff --git a/tests/core/brain/content-hash.test.ts b/tests/core/brain/content-hash.test.tsnew file mode 100644index 00000000..71cc1104--- /dev/null+++ b/tests/core/brain/content-hash.test.ts@@ -0,0 +1,96 @@+/**+ * Content-hash helper for confirmed preferences. The hash is written+ * into `_content_hash` on promotion and recomputed at read time; a+ * mismatch surfaces as a `drift_detected` event (Task 4).+ */++import { describe, expect, test } from "bun:test";++import {+ computeContentHash,+ verifyContentHash,+} from "../../../src/core/brain/content-hash.ts";++describe("computeContentHash", () => {+ test("returns a 64-char lowercase hex sha256 digest", () => {+ const hash = computeContentHash("do the right thing", "coding");+ expect(hash).toMatch(/^[0-9a-f]{64}$/);+ });++ test("is deterministic for the same (principle, scope)", () => {+ const a = computeContentHash("do the right thing", "coding");+ const b = computeContentHash("do the right thing", "coding");+ expect(a).toBe(b);+ });++ test("differs when principle differs", () => {+ const a = computeContentHash("do A", "coding");+ const b = computeContentHash("do B", "coding");+ expect(a).not.toBe(b);+ });++ test("differs when scope differs", () => {+ const a = computeContentHash("do A", "coding");+ const b = computeContentHash("do A", "writing");+ expect(a).not.toBe(b);+ });++ test("treats absent and empty scope the same way (both normalise to empty)", () => {+ // The frontmatter writer never emits an empty `scope`; absent means+ // "no scope". Hash must reflect this so a parser later reading the+ // file (which sees scope as undefined) recomputes the same digest.+ const a = computeContentHash("do A");+ const b = computeContentHash("do A", "");+ const c = computeContentHash("do A", undefined);+ expect(a).toBe(b);+ expect(a).toBe(c);+ });++ test("trims leading and trailing whitespace from principle and scope", () => {+ // Frontmatter round-trips can introduce whitespace; the hash must be+ // stable across " text " and "text" so a no-op rewrite does not+ // appear as drift.+ const a = computeContentHash("the rule", "scope");+ const b = computeContentHash(" the rule ", " scope ");+ expect(a).toBe(b);+ });+});++describe("verifyContentHash", () => {+ test("returns ok=true when the stored hash matches the recomputed hash", () => {+ const principle = "explain the why, not the what";+ const scope = "writing";+ const stored = computeContentHash(principle, scope);+ const result = verifyContentHash({ principle, scope, content_hash: stored });+ expect(result.ok).toBe(true);+ expect(result.expected).toBe(stored);+ expect(result.observed).toBe(stored);+ });++ test("returns ok=false when the stored hash diverges from the recomputed hash", () => {+ const result = verifyContentHash({+ principle: "altered principle after a hand edit",+ scope: "coding",+ content_hash: "0".repeat(64),+ });+ expect(result.ok).toBe(false);+ expect(result.expected).toBe(computeContentHash(+ "altered principle after a hand edit",+ "coding",+ ));+ expect(result.observed).toBe("0".repeat(64));+ });++ test("returns ok=true with neutral output when content_hash is absent (legacy)", () => {+ const result = verifyContentHash({+ principle: "p",+ scope: "s",+ content_hash: undefined,+ });+ expect(result.ok).toBe(true);+ // No expected/observed when no hash to compare against - the caller+ // must not log a drift event in this case.+ expect(result.expected).toBeUndefined();+ expect(result.observed).toBeUndefined();+ });+});diff --git a/tests/core/brain/doctor-drift.test.ts b/tests/core/brain/doctor-drift.test.tsnew file mode 100644index 00000000..823a121d--- /dev/null+++ b/tests/core/brain/doctor-drift.test.ts@@ -0,0 +1,149 @@+/**+ * `brain_doctor` content-hash drift surface. The integrity suite's+ * Feature 1 reads each confirmed preference, recomputes the hash, and+ * surfaces a `content-hash-drift` warning when the stored hash diverges+ * from the recomputed value. Legacy preferences without `_content_hash`+ * are silent (no false positives), and non-confirmed preferences are+ * skipped entirely.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { computeContentHash } from "../../../src/core/brain/content-hash.ts";+import { runDoctor } from "../../../src/core/brain/doctor.ts";+import { brainDirs } from "../../../src/core/brain/paths.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-doctor-drift-"));+ // Minimal Brain skeleton: _brain.yaml + _BRAIN.md + preferences/.+ const dirs = brainDirs(vault);+ mkdirSync(dirs.brain, { recursive: true });+ mkdirSync(dirs.preferences, { recursive: true });+ mkdirSync(dirs.log, { recursive: true });+ writeFileSync(+ join(dirs.brain, "_brain.yaml"),+ `schema_version: 1+primary_agent: null+dream:+ candidate_threshold: 2+ unconfirmed_window_days: 7+ contradiction_window_days: 14+retire:+ stale_evidence_days: 90+confidence:+ low_max_applied: 2+ medium_min: 0.4+ high_min: 0.7+snapshots:+ retention_count: 10+`,+ "utf8",+ );+ writeFileSync(+ join(dirs.brain, "_BRAIN.md"),+ "---\ntitle: Brain\n---\n",+ "utf8",+ );+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++function writeConfirmedPref(+ slug: string,+ opts: {+ principle: string;+ scope?: string;+ content_hash?: string;+ },+): string {+ const dirs = brainDirs(vault);+ const path = join(dirs.preferences, `pref-${slug}.md`);+ const lines = [+ "---",+ "kind: brain-preference",+ `id: pref-${slug}`,+ 'created_at: "2026-05-01T00:00:00Z"',+ '_confirmed_at: "2026-05-02T00:00:00Z"',+ 'unconfirmed_until: "2026-05-08T00:00:00Z"',+ "tags: [brain, brain/preference, brain/topic/writing]",+ "topic: writing",+ "_status: confirmed",+ `principle: ${opts.principle}`,+ "_evidenced_by: []",+ "_applied_count: 1",+ "_violated_count: 0",+ '_last_evidence_at: "2026-05-02T00:00:00Z"',+ "_confidence: high",+ "_confidence_value: 0.8",+ "pinned: false",+ ];+ if (opts.scope) lines.push(`scope: ${opts.scope}`);+ if (opts.content_hash) lines.push(`_content_hash: ${opts.content_hash}`);+ lines.push("---", "");+ writeFileSync(path, lines.join("\n"), "utf8");+ return path;+}++describe("runDoctor content-hash drift detection", () => {+ test("emits no drift warning when stored hash matches the live principle", () => {+ const principle = "the in-sync principle text";+ const hash = computeContentHash(principle, undefined);+ writeConfirmedPref("clean", { principle, content_hash: hash });+ const result = runDoctor(vault);+ const drift = result.warnings.filter(+ (i) => i.code === "content-hash-drift",+ );+ expect(drift).toEqual([]);+ });++ test("emits a content-hash-drift warning when the stored hash diverges", () => {+ const principle = "edited after hand modification";+ // Stored hash is for a DIFFERENT principle.+ const staleHash = computeContentHash("the original frozen principle", undefined);+ const path = writeConfirmedPref("drifted", {+ principle,+ content_hash: staleHash,+ });+ const result = runDoctor(vault);+ const drift = result.warnings.filter(+ (i) => i.code === "content-hash-drift",+ );+ expect(drift).toHaveLength(1);+ expect(drift[0]?.path).toBe(path);+ expect(drift[0]?.message).toContain("drift");+ });++ test("does not warn on preferences without _content_hash (legacy / unconfirmed)", () => {+ writeConfirmedPref("legacy", {+ principle: "no hash stored at all",+ // content_hash intentionally omitted+ });+ const result = runDoctor(vault);+ const drift = result.warnings.filter(+ (i) => i.code === "content-hash-drift",+ );+ expect(drift).toEqual([]);+ });++ test("scope changes are detected as drift", () => {+ const principle = "rule with scope";+ // Stored hash includes scope=writing; live scope is coding.+ const staleHash = computeContentHash(principle, "writing");+ writeConfirmedPref("scope-drift", {+ principle,+ scope: "coding",+ content_hash: staleHash,+ });+ const result = runDoctor(vault);+ const drift = result.warnings.filter(+ (i) => i.code === "content-hash-drift",+ );+ expect(drift).toHaveLength(1);+ });+});diff --git a/tests/core/brain/dream-content-hash-promotion.test.ts b/tests/core/brain/dream-content-hash-promotion.test.tsnew file mode 100644index 00000000..d4b5bcaf--- /dev/null+++ b/tests/core/brain/dream-content-hash-promotion.test.ts@@ -0,0 +1,96 @@+/**+ * Integration coverage for the Brain Integrity Suite Critical fix+ * surfaced during code review: dream's promotion path must produce+ * an on-disk `_content_hash` for every confirmed preference, so the+ * doctor's drift detection has something to compare against.+ *+ * The proof is end-to-end: drive a fresh dream run that promotes an+ * unconfirmed pref to confirmed, then read the resulting file and+ * assert the field is present and matches the canonical hash of the+ * live (principle, scope).+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ mkdtempSync,+ readFileSync,+ rmSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { appendApplyEvidence } from "../../../src/core/brain/apply-evidence.ts";+import { computeContentHash } from "../../../src/core/brain/content-hash.ts";+import { dream } from "../../../src/core/brain/dream.ts";+import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { preferencePath } from "../../../src/core/brain/paths.ts";+import { parsePreference } from "../../../src/core/brain/preference.ts";+import { writeSignal } from "../../../src/core/brain/signal.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-promo-hash-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-promo-hash-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++describe("dream content_hash on promotion", () => {+ test("an unconfirmed -> confirmed transition writes _content_hash matching the live principle", () => {+ // Three positive signals on the same topic clear the candidate+ // threshold; dream creates an unconfirmed pref.+ const topic = "no-magic-numbers";+ const principle = "Replace magic numbers with named constants in production code.";+ for (let i = 0; i < 3; i++) {+ writeSignal(vault, {+ topic,+ signal: "positive",+ agent: "claude",+ principle,+ created_at: `2026-05-12T0${i + 1}:00:00Z`,+ date: "2026-05-12",+ slug: `seed-${i}`,+ scope: "coding",+ });+ }+ const first = dream(vault, { now: new Date("2026-05-12T10:00:00Z") });+ expect(first.new_unconfirmed).toContain(`pref-${topic}`);++ // Record an apply-evidence for the new pref; the next dream pass+ // observes the applied event and flips the pref to confirmed.+ appendApplyEvidence(+ vault,+ {+ pref_id: `pref-${topic}`,+ artifact: "[[src/lib/example.ts]]",+ result: "applied",+ agent: "claude",+ },+ { now: new Date("2026-05-12T11:00:00Z") },+ );++ const second = dream(vault, { now: new Date("2026-05-12T12:00:00Z") });+ expect(second.confirmed).toContain(`pref-${topic}`);++ // Now the on-disk pref must carry _content_hash matching the+ // canonical hash of (principle, scope). Without this fix the+ // doctor's drift detection has nothing to compare against and+ // Feature 1 silently no-ops on every real vault.+ const path = preferencePath(vault, topic);+ const text = readFileSync(path, "utf8");+ expect(text).toContain("_content_hash:");+ const parsed = parsePreference(path);+ expect(parsed.status).toBe("confirmed");+ expect(parsed.content_hash).toBe(+ computeContentHash(parsed.principle, parsed.scope),+ );+ });+});diff --git a/tests/core/brain/dream-destructive-gate.test.ts b/tests/core/brain/dream-destructive-gate.test.tsnew file mode 100644index 00000000..b32a85e1--- /dev/null+++ b/tests/core/brain/dream-destructive-gate.test.ts@@ -0,0 +1,186 @@+/**+ * Brain Integrity Suite (v0.12.0) destructive-from-confirmed gate.+ *+ * Two layers of coverage:+ *+ * - `shouldGateRetireFromConfirmed` pure decision: every branch of+ * the gate logic exercised in isolation. No vault, no I/O.+ * - `dream()` smoke: when the config field is absent, the new+ * `gated_retires` field on `DreamRunSummary` exists and reads as+ * an empty array. This preserves the pre-v0.12.0 contract for+ * every consumer that did not opt in to the gate.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ dream,+ shouldGateRetireFromConfirmed,+} from "../../../src/core/brain/dream.ts";+import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import {+ BRAIN_PREFERENCE_STATUS,+ BRAIN_RETIRED_REASON,+ type BrainPreference,+} from "../../../src/core/brain/types.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";++const pref = (overrides: Partial<BrainPreference> = {}): BrainPreference => ({+ kind: "brain-preference",+ id: "pref-gate-test",+ created_at: "2026-01-01T00:00:00Z",+ confirmed_at: "2026-01-02T00:00:00Z",+ unconfirmed_until: "2026-01-08T00:00:00Z",+ tags: [],+ topic: "gating",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ principle: "the gated principle",+ evidenced_by: [],+ applied_count: 1,+ violated_count: 0,+ last_evidence_at: "2026-01-02T00:00:00Z",+ confidence: "high",+ confidence_value: 0.9,+ pinned: false,+ ...overrides,+});++describe("shouldGateRetireFromConfirmed", () => {+ test("returns false when threshold is undefined (default-off)", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref(),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ undefined,+ ),+ ).toBe(false);+ });++ test("returns false when threshold is 0 or negative", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref(),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ 0,+ ),+ ).toBe(false);+ expect(+ shouldGateRetireFromConfirmed(+ pref(),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ -1,+ ),+ ).toBe(false);+ });++ test("returns true when confirmed + unpinned + evidence below threshold", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({ applied_count: 1, violated_count: 0 }),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ 3,+ ),+ ).toBe(true);+ });++ test("returns false when accumulated evidence meets or exceeds threshold", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({ applied_count: 3, violated_count: 0 }),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ 3,+ ),+ ).toBe(false);+ expect(+ shouldGateRetireFromConfirmed(+ pref({ applied_count: 2, violated_count: 1 }),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ 3,+ ),+ ).toBe(false);+ });++ test("never gates an operator-initiated user-rejected retire", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({ applied_count: 0, violated_count: 0 }),+ BRAIN_RETIRED_REASON.userRejected,+ 10,+ ),+ ).toBe(false);+ });++ test("never gates a merge-driven retire", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({ applied_count: 0, violated_count: 0 }),+ BRAIN_RETIRED_REASON.mergedInto,+ 10,+ ),+ ).toBe(false);+ });++ test("never gates a non-confirmed source (unconfirmed / quarantine)", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ applied_count: 0,+ violated_count: 0,+ }),+ BRAIN_RETIRED_REASON.expiredUnconfirmed,+ 10,+ ),+ ).toBe(false);+ expect(+ shouldGateRetireFromConfirmed(+ pref({+ status: BRAIN_PREFERENCE_STATUS.quarantine,+ applied_count: 0,+ violated_count: 0,+ }),+ BRAIN_RETIRED_REASON.quarantineViolated,+ 10,+ ),+ ).toBe(false);+ });++ test("never gates a pinned preference", () => {+ expect(+ shouldGateRetireFromConfirmed(+ pref({ pinned: true, applied_count: 0, violated_count: 0 }),+ BRAIN_RETIRED_REASON.staleNoEvidence,+ 10,+ ),+ ).toBe(false);+ });+});++describe("dream() gated_retires field", () => {+ let vault: string;+ let configHome: string;++ beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-gate-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-gate-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+ });+ afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+ });++ test("a fresh-bootstrap dream run returns gated_retires as an empty array", () => {+ const summary = dream(vault, {+ now: new Date("2026-05-27T12:00:00Z"),+ dryRun: true,+ });+ expect(Array.isArray(summary.gated_retires)).toBe(true);+ expect(summary.gated_retires).toEqual([]);+ });+});diff --git a/tests/core/brain/dream-workrun.test.ts b/tests/core/brain/dream-workrun.test.tsnew file mode 100644index 00000000..a688f225--- /dev/null+++ b/tests/core/brain/dream-workrun.test.ts@@ -0,0 +1,165 @@+/**+ * Durable workrun checkpoints for the dream pass (Brain Integrity+ * Suite, Feature 4). Each dream invocation writes a JSONL workrun+ * file under `Brain/log/dream-runs/<run-id>.jsonl`; the file records+ * phase transitions so a crash mid-pass leaves an inspectable trail.+ *+ * Recovery is non-resuming: `scanDanglingWorkruns(vault)` returns the+ * paths of every file whose last event is neither `finalized` nor+ * `interrupted`. The next dream pass logs a `recovered` event and the+ * brain_doctor surfaces the dangling files as warnings.+ *+ * Dry-run never emits a workrun - the workrun is part of the+ * durable side-effect surface and dry-runs must not mutate disk.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ openWorkrun,+ scanDanglingWorkruns,+ WORKRUN_PHASE,+} from "../../../src/core/brain/dream-workrun.ts";+import {+ dreamRunsDir,+ dreamWorkrunPath,+} from "../../../src/core/brain/paths.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-workrun-"));+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++function parseJsonl(path: string): Array<Record<string, unknown>> {+ const text = readFileSync(path, "utf8");+ return text+ .split("\n")+ .filter((l) => l.trim().length > 0)+ .map((l) => JSON.parse(l) as Record<string, unknown>);+}++describe("WORKRUN_PHASE", () => {+ test("exposes the five canonical phase strings + interrupted", () => {+ expect(WORKRUN_PHASE.started).toBe("started");+ expect(WORKRUN_PHASE.clusterComplete).toBe("cluster_complete");+ expect(WORKRUN_PHASE.promoteComplete).toBe("promote_complete");+ expect(WORKRUN_PHASE.retireComplete).toBe("retire_complete");+ expect(WORKRUN_PHASE.finalized).toBe("finalized");+ expect(WORKRUN_PHASE.interrupted).toBe("interrupted");+ });+});++describe("openWorkrun + checkpoint + finalize", () => {+ test("creates a JSONL file under Brain/log/dream-runs/ with a started line", () => {+ const runId = "dream-2026-05-27-120000";+ const handle = openWorkrun(vault, runId);+ expect(handle.path).toBe(dreamWorkrunPath(vault, runId));+ expect(existsSync(handle.path)).toBe(true);+ const lines = parseJsonl(handle.path);+ expect(lines).toHaveLength(1);+ expect(lines[0]?.phase).toBe("started");+ expect(lines[0]?.run_id).toBe(runId);+ expect(typeof lines[0]?.at).toBe("string");+ handle.finalize();+ });++ test("checkpoint appends one line per phase, in invocation order", () => {+ const runId = "dream-2026-05-27-120001";+ const handle = openWorkrun(vault, runId);+ handle.checkpoint(WORKRUN_PHASE.clusterComplete);+ handle.checkpoint(WORKRUN_PHASE.promoteComplete);+ handle.checkpoint(WORKRUN_PHASE.retireComplete);+ handle.finalize();+ const lines = parseJsonl(handle.path);+ expect(lines.map((l) => l.phase)).toEqual([+ "started",+ "cluster_complete",+ "promote_complete",+ "retire_complete",+ "finalized",+ ]);+ });++ test("finalize is idempotent (second call is a no-op)", () => {+ const handle = openWorkrun(vault, "dream-2026-05-27-120002");+ handle.finalize();+ handle.finalize();+ const lines = parseJsonl(handle.path);+ expect(lines.filter((l) => l.phase === "finalized")).toHaveLength(1);+ });++ test("interrupt records an interrupted line with optional reason", () => {+ const handle = openWorkrun(vault, "dream-2026-05-27-120003");+ handle.interrupt("test crash");+ const lines = parseJsonl(handle.path);+ const last = lines[lines.length - 1];+ expect(last?.phase).toBe("interrupted");+ expect(last?.reason).toBe("test crash");+ });++ test("checkpoint after finalize is rejected (silent no-op)", () => {+ const handle = openWorkrun(vault, "dream-2026-05-27-120004");+ handle.finalize();+ handle.checkpoint(WORKRUN_PHASE.promoteComplete);+ const lines = parseJsonl(handle.path);+ // started + finalized, nothing else+ expect(lines.map((l) => l.phase)).toEqual(["started", "finalized"]);+ });+});++describe("scanDanglingWorkruns", () => {+ test("returns empty when no workruns directory exists", () => {+ expect(scanDanglingWorkruns(vault)).toEqual([]);+ });++ test("returns empty when every workrun file ends in finalized", () => {+ const a = openWorkrun(vault, "dream-2026-05-27-200001");+ a.finalize();+ const b = openWorkrun(vault, "dream-2026-05-27-200002");+ b.checkpoint(WORKRUN_PHASE.clusterComplete);+ b.finalize();+ expect(scanDanglingWorkruns(vault)).toEqual([]);+ });++ test("returns empty when a workrun ends in interrupted", () => {+ const handle = openWorkrun(vault, "dream-2026-05-27-200003");+ handle.checkpoint(WORKRUN_PHASE.clusterComplete);+ handle.interrupt("test");+ expect(scanDanglingWorkruns(vault)).toEqual([]);+ });++ test("returns paths of files whose last line is neither finalized nor interrupted", () => {+ const a = openWorkrun(vault, "dream-2026-05-27-200004");+ a.checkpoint(WORKRUN_PHASE.clusterComplete);+ // no finalize -> dangling++ const b = openWorkrun(vault, "dream-2026-05-27-200005");+ b.finalize();++ const dangling = scanDanglingWorkruns(vault).sort();+ expect(dangling).toEqual([a.path]);+ });++ test("tolerates malformed lines (a corrupt workrun is treated as dangling)", () => {+ mkdirSync(dreamRunsDir(vault), { recursive: true });+ const corruptPath = join(dreamRunsDir(vault), "dream-2026-05-27-9.jsonl");+ writeFileSync(corruptPath, "not json at all\n", "utf8");+ const dangling = scanDanglingWorkruns(vault);+ expect(dangling).toContain(corruptPath);+ });+});diff --git a/tests/core/brain/preference-collision.test.ts b/tests/core/brain/preference-collision.test.tsnew file mode 100644index 00000000..a5a91cac--- /dev/null+++ b/tests/core/brain/preference-collision.test.ts@@ -0,0 +1,261 @@+/**+ * Collision-detection expectations for `writePreferenceTxn`. Three+ * factory functions cover the typed collision modes that depend on+ * proposed-vs-existing state. `SourceLock` lives inside the lock+ * acquire itself and is exercised in `preference-txn.test.ts`.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { computeContentHash } from "../../../src/core/brain/content-hash.ts";+import {+ brainDirs,+ preferencePath,+} from "../../../src/core/brain/paths.ts";+import { writePreference } from "../../../src/core/brain/preference.ts";+import {+ BRAIN_COLLISION_KIND,+ BrainCollisionError,+ expectRevision,+ noDuplicateWriteWithin,+ noUnsafeShrink,+ writePreferenceTxn,+} from "../../../src/core/brain/preference-txn.ts";+import {+ BRAIN_PREFERENCE_STATUS,+} from "../../../src/core/brain/types.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-pref-collision-"));+ mkdirSync(brainDirs(vault).preferences, { recursive: true });+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++const baseInput = (overrides: Record<string, unknown> = {}) => ({+ slug: "collision-rule",+ topic: "test-topic",+ principle: "the original long-form principle text that has plenty of length",+ created_at: "2026-05-26T12:00:00Z",+ unconfirmed_until: "2026-06-02T12:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ confirmed_at: "2026-05-27T12:00:00Z",+ evidenced_by: [] as ReadonlyArray<string>,+ ...overrides,+});++describe("expectRevision", () => {+ test("passes when stored revision matches expected", () => {+ writePreferenceTxn(vault, baseInput({ revision: 3 }), [], {});+ // Same revision -> ok.+ writePreferenceTxn(+ vault,+ baseInput({+ revision: 4,+ principle: "the original long-form principle text revised slightly",+ }),+ [expectRevision(3)],+ { overwrite: true },+ );+ const text = readFileSync(preferencePath(vault, "collision-rule"), "utf8");+ expect(text).toContain("_revision: 4");+ });++ test("raises BrainCollisionError(StaleUpdate) when stored revision differs", () => {+ writePreferenceTxn(vault, baseInput({ revision: 5 }), [], {});+ let caught: unknown;+ try {+ writePreferenceTxn(+ vault,+ baseInput({ revision: 6 }),+ [expectRevision(2)],+ { overwrite: true },+ );+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);+ expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");+ });++ test("expectRevision treats a writePreference-baseline file (no revision stamp) as 0", () => {+ // Bypass the txn for the baseline so the smart-default auto-stamp+ // does not kick in. This mirrors a legacy preference written by a+ // pre-v0.12.0 dream pass.+ writePreference(vault, baseInput({}));+ writePreferenceTxn(+ vault,+ baseInput({+ revision: 1,+ principle:+ "edited principle text after the no-revision baseline",+ }),+ [expectRevision(0)],+ { overwrite: true },+ );+ const text = readFileSync(preferencePath(vault, "collision-rule"), "utf8");+ expect(text).toContain("_revision: 1");+ });+});++describe("noUnsafeShrink", () => {+ test("passes when there is no existing preference (first write)", () => {+ writePreferenceTxn(+ vault,+ baseInput({ slug: "fresh", principle: "short" }),+ [noUnsafeShrink(0.5)],+ {},+ );+ expect(+ require("node:fs").existsSync(preferencePath(vault, "fresh")),+ ).toBe(true);+ });++ test("passes when new principle is the same length or longer", () => {+ writePreferenceTxn(vault, baseInput({}), [], {});+ writePreferenceTxn(+ vault,+ baseInput({+ principle:+ "the original long-form principle text that has plenty of length, now with an extension",+ }),+ [noUnsafeShrink(0.5)],+ { overwrite: true },+ );+ });++ test("raises BrainCollisionError(UnsafeShrink) when new principle drops below the ratio", () => {+ writePreferenceTxn(vault, baseInput({}), [], {});+ let caught: unknown;+ try {+ writePreferenceTxn(+ vault,+ baseInput({ principle: "tiny" }),+ [noUnsafeShrink(0.5)],+ { overwrite: true },+ );+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);+ expect((caught as BrainCollisionError).kind).toBe("UnsafeShrink");+ });++ test("the existing on-disk content is not modified when the shrink gate fires", () => {+ const r = writePreferenceTxn(vault, baseInput({}), [], {});+ const before = readFileSync(r.path, "utf8");+ try {+ writePreferenceTxn(+ vault,+ baseInput({ principle: "x" }),+ [noUnsafeShrink(0.5)],+ { overwrite: true },+ );+ } catch {+ // expected+ }+ const after = readFileSync(r.path, "utf8");+ expect(after).toBe(before);+ });+});++describe("noDuplicateWriteWithin", () => {+ test("passes when the existing preference has no content_hash (legacy)", () => {+ writePreferenceTxn(vault, baseInput({}), [], {});+ writePreferenceTxn(+ vault,+ baseInput({+ principle: "the original long-form principle text that has plenty of length",+ last_evidence_at: "2026-05-26T12:00:00Z",+ }),+ [noDuplicateWriteWithin(60_000, () => new Date("2026-05-26T12:00:30Z"))],+ { overwrite: true },+ );+ });++ test("raises BrainCollisionError(DuplicateWrite) when content_hash matches AND last evidence is within the window", () => {+ const principle = "the original long-form principle text that has plenty of length";+ const hash = computeContentHash(principle, undefined);+ writePreferenceTxn(+ vault,+ baseInput({+ principle,+ content_hash: hash,+ last_evidence_at: "2026-05-26T12:00:00Z",+ }),+ [],+ {},+ );++ let caught: unknown;+ try {+ writePreferenceTxn(+ vault,+ baseInput({+ principle,+ content_hash: hash,+ last_evidence_at: "2026-05-26T12:00:00Z",+ }),+ [noDuplicateWriteWithin(60_000, () => new Date("2026-05-26T12:00:30Z"))],+ { overwrite: true },+ );+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);+ expect((caught as BrainCollisionError).kind).toBe("DuplicateWrite");+ });++ test("passes when the window has elapsed even if content_hash matches", () => {+ const principle = "the original long-form principle text that has plenty of length";+ const hash = computeContentHash(principle, undefined);+ writePreferenceTxn(+ vault,+ baseInput({+ principle,+ content_hash: hash,+ last_evidence_at: "2026-05-26T12:00:00Z",+ }),+ [],+ {},+ );++ writePreferenceTxn(+ vault,+ baseInput({+ principle,+ content_hash: hash,+ last_evidence_at: "2026-05-26T13:00:00Z",+ }),+ [+ noDuplicateWriteWithin(+ 60_000,+ // 70s elapsed since the existing last_evidence_at+ () => new Date("2026-05-26T12:01:10Z"),+ ),+ ],+ { overwrite: true },+ );+ });+});++describe("BRAIN_COLLISION_KIND completeness", () => {+ test("all four discriminants are covered by either lock acquire or an expectation factory", () => {+ // Sanity assertion - guards against silent renames of the kind table.+ const expected = [+ "DuplicateWrite",+ "SourceLock",+ "StaleUpdate",+ "UnsafeShrink",+ ] as const;+ const actual = [...Object.values(BRAIN_COLLISION_KIND)].sort();+ const expectedSorted = [...expected].sort();+ expect(actual).toEqual(expectedSorted);+ });+});diff --git a/tests/core/brain/preference-integrity-fields.test.ts b/tests/core/brain/preference-integrity-fields.test.tsnew file mode 100644index 00000000..d50c2b94--- /dev/null+++ b/tests/core/brain/preference-integrity-fields.test.ts@@ -0,0 +1,156 @@+/**+ * Frontmatter emission + parse coverage for the two integrity fields+ * added by the brain integrity suite:+ *+ * - `_revision` (always emitted; defaults to 0 when caller omits)+ * - `_content_hash` (only emitted when caller supplies one, which+ * dream does on every promotion to `confirmed`)+ *+ * Round-trip invariant: `parsePreference(writePreference(input))` must+ * surface the same `revision` and `content_hash` values the writer+ * received.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { computeContentHash } from "../../../src/core/brain/content-hash.ts";+import {+ parsePreference,+ writePreference,+ type WritePreferenceInput,+} from "../../../src/core/brain/preference.ts";+import {+ BRAIN_CONFIDENCE,+ BRAIN_PREFERENCE_STATUS,+} from "../../../src/core/brain/types.ts";++let vault: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-pref-integrity-"));+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+});++function basePref(+ slug: string,+ overrides: Partial<WritePreferenceInput> = {},+): WritePreferenceInput {+ return {+ slug,+ topic: "writing",+ principle: `Principle for ${slug}`,+ created_at: "2026-05-26T12:00:00Z",+ unconfirmed_until: "2026-06-02T12:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ evidenced_by: [],+ pinned: false,+ confidence: BRAIN_CONFIDENCE.low,+ ...overrides,+ };+}++describe("writePreference - _revision emission", () => {+ test("does NOT emit _revision when caller omits the field (legacy byte-identical)", () => {+ const res = writePreference(vault, basePref("rev-default"));+ const text = readFileSync(res.path, "utf8");+ expect(text).not.toContain("_revision:");+ });++ test("emits the supplied revision when caller provides one", () => {+ const res = writePreference(+ vault,+ basePref("rev-supplied", { revision: 7 }),+ );+ const text = readFileSync(res.path, "utf8");+ expect(text).toContain("_revision: 7");+ });++ test("parsePreference reads _revision back as a number", () => {+ const res = writePreference(+ vault,+ basePref("rev-roundtrip", { revision: 12 }),+ );+ const parsed = parsePreference(res.path);+ expect(parsed.revision).toBe(12);+ });++ test("parsePreference defaults revision to 0 when the field is absent on disk", () => {+ // Hand-write a frontmatter without _revision to simulate a legacy+ // file - the reader must not crash and must report 0.+ const path = join(vault, "Brain", "preferences", "pref-legacy.md");+ require("node:fs").writeFileSync(+ path,+ `---+kind: brain-preference+id: pref-legacy+created_at: 2026-01-01T00:00:00Z+_confirmed_at: "null"+unconfirmed_until: 2026-01-08T00:00:00Z+tags: [brain, brain/preference, brain/topic/writing]+topic: writing+_status: unconfirmed+principle: legacy principle+_evidenced_by: []+_applied_count: 0+_violated_count: 0+_last_evidence_at: "null"+_confidence: low+_confidence_value: "null"+pinned: false+---+`,+ "utf8",+ );+ const parsed = parsePreference(path);+ expect(parsed.revision).toBe(0);+ });+});++describe("writePreference - _content_hash emission", () => {+ test("does NOT emit _content_hash when caller omits the field", () => {+ const res = writePreference(vault, basePref("hash-absent"));+ const text = readFileSync(res.path, "utf8");+ expect(text).not.toContain("_content_hash:");+ });++ test("emits the supplied _content_hash verbatim", () => {+ const hash = computeContentHash("Principle for hash-present", undefined);+ const res = writePreference(+ vault,+ basePref("hash-present", {+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ confirmed_at: "2026-05-26T13:00:00Z",+ content_hash: hash,+ }),+ );+ const text = readFileSync(res.path, "utf8");+ expect(text).toContain(`_content_hash: ${hash}`);+ });++ test("parsePreference reads _content_hash back as a string", () => {+ const hash = computeContentHash("Principle for hash-roundtrip", "writing");+ const res = writePreference(+ vault,+ basePref("hash-roundtrip", {+ scope: "writing",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ confirmed_at: "2026-05-26T13:00:00Z",+ content_hash: hash,+ }),+ );+ const parsed = parsePreference(res.path);+ expect(parsed.content_hash).toBe(hash);+ });++ test("parsePreference leaves content_hash undefined when the field is absent on disk", () => {+ const res = writePreference(vault, basePref("hash-missing"));+ const parsed = parsePreference(res.path);+ expect(parsed.content_hash).toBeUndefined();+ });+});diff --git a/tests/core/brain/preference-txn.test.ts b/tests/core/brain/preference-txn.test.tsnew file mode 100644index 00000000..13800e60--- /dev/null+++ b/tests/core/brain/preference-txn.test.ts@@ -0,0 +1,222 @@+/**+ * `writePreferenceTxn` - the single chokepoint that wraps every+ * preference write. Acquires the sync lock, re-reads the current+ * file state, runs an expectations chain that can raise typed+ * `BrainCollisionError`, then mutates via `writeFrontmatterAtomic`.+ */++import { afterAll, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ brainDirs,+ preferencePath,+} from "../../../src/core/brain/paths.ts";+import { parsePreference } from "../../../src/core/brain/preference.ts";+import {+ BrainCollisionError,+ BRAIN_COLLISION_KIND,+ writePreferenceTxn,+ type WritePreferenceExpectation,+} from "../../../src/core/brain/preference-txn.ts";+import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";+import { BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";++let tmpRoot: string;+let vault: string;++beforeEach(() => {+ tmpRoot = mkdtempSync(join(tmpdir(), "osb-pref-txn-"));+ vault = tmpRoot;+ // Ensure Brain/preferences/ exists so the writer can drop the file.+ require("node:fs").mkdirSync(brainDirs(vault).preferences, {+ recursive: true,+ });+});++afterAll(() => {+ if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });+});++const baseInput = (overrides: Record<string, unknown> = {}) => ({+ slug: "test-rule",+ topic: "test-topic",+ principle: "do the right thing in production code",+ created_at: "2026-05-26T12:00:00Z",+ unconfirmed_until: "2026-06-02T12:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ evidenced_by: [] as ReadonlyArray<string>,+ ...overrides,+});++describe("BRAIN_COLLISION_KIND", () => {+ test("exposes the four discriminant string values", () => {+ expect(BRAIN_COLLISION_KIND.staleUpdate).toBe("StaleUpdate");+ expect(BRAIN_COLLISION_KIND.unsafeShrink).toBe("UnsafeShrink");+ expect(BRAIN_COLLISION_KIND.sourceLock).toBe("SourceLock");+ expect(BRAIN_COLLISION_KIND.duplicateWrite).toBe("DuplicateWrite");+ });+});++describe("BrainCollisionError", () => {+ test("kind field is preserved on instances", () => {+ const err = new BrainCollisionError(+ BRAIN_COLLISION_KIND.staleUpdate,+ "test message",+ );+ expect(err).toBeInstanceOf(Error);+ expect(err.kind).toBe("StaleUpdate");+ expect(err.name).toBe("BrainCollisionError");+ expect(err.message).toBe("test message");+ });+});++describe("writePreferenceTxn", () => {+ test("with empty expectations writes a preference identical to writePreference", () => {+ const result = writePreferenceTxn(vault, baseInput(), [], {});+ expect(result.id).toBe("pref-test-rule");+ expect(existsSync(result.path)).toBe(true);+ // Lock file must be cleaned up after the txn returns.+ expect(existsSync(result.path + ".lock")).toBe(false);+ const parsed = parsePreference(result.path);+ expect(parsed.principle).toBe("do the right thing in production code");+ expect(parsed.topic).toBe("test-topic");+ });++ test("raises BrainCollisionError(SourceLock) when the lock is already held", () => {+ const path = preferencePath(vault, "held-rule");+ const handle = acquireLockSync(path);+ try {+ let caught: unknown;+ try {+ writePreferenceTxn(vault, baseInput({ slug: "held-rule" }), [], {});+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);+ expect((caught as BrainCollisionError).kind).toBe("SourceLock");+ } finally {+ handle.release();+ }+ });++ test("runs expectations chain in order; first failure short-circuits", () => {+ // First write to seed the on-disk state.+ writePreferenceTxn(vault, baseInput({ slug: "chain-rule" }), [], {});++ const calls: string[] = [];+ const ok: WritePreferenceExpectation = () => {+ calls.push("ok");+ };+ const fail: WritePreferenceExpectation = () => {+ calls.push("fail");+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.staleUpdate,+ "deliberate failure",+ );+ };+ const never: WritePreferenceExpectation = () => {+ calls.push("never");+ };++ let caught: unknown;+ try {+ writePreferenceTxn(+ vault,+ baseInput({+ slug: "chain-rule",+ principle: "updated principle text",+ }),+ [ok, fail, never],+ { overwrite: true },+ );+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);+ expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");+ expect(calls).toEqual(["ok", "fail"]); // `never` was not invoked+ });++ test("releases the lock even when an expectation throws", () => {+ writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {});+ const failingExpectation: WritePreferenceExpectation = () => {+ throw new BrainCollisionError(+ BRAIN_COLLISION_KIND.duplicateWrite,+ "blocked",+ );+ };++ let caught: unknown;+ try {+ writePreferenceTxn(+ vault,+ baseInput({ slug: "release-rule" }),+ [failingExpectation],+ { overwrite: true },+ );+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(BrainCollisionError);++ // Lock must be released even though the write was aborted.+ const lockPath = preferencePath(vault, "release-rule") + ".lock";+ expect(existsSync(lockPath)).toBe(false);++ // A follow-up write with empty expectations must succeed.+ const ok = writePreferenceTxn(+ vault,+ baseInput({ slug: "release-rule" }),+ [],+ { overwrite: true },+ );+ expect(existsSync(ok.path)).toBe(true);+ });++ test("expectation receives the existing preference when overwriting", () => {+ writePreferenceTxn(+ vault,+ baseInput({ slug: "ctx-rule", principle: "original principle text" }),+ [],+ {},+ );++ const observed: { principle: string | null } = { principle: null };+ const inspect: WritePreferenceExpectation = (ctx) => {+ observed.principle = ctx.existing?.principle ?? null;+ };++ writePreferenceTxn(+ vault,+ baseInput({ slug: "ctx-rule", principle: "replacement principle text" }),+ [inspect],+ { overwrite: true },+ );+ expect(observed.principle).toBe("original principle text");+ });++ test("expectation context shows existing=null on first write", () => {+ const observed: { existing: unknown } = { existing: "unset" };+ const inspect: WritePreferenceExpectation = (ctx) => {+ observed.existing = ctx.existing;+ };+ writePreferenceTxn(vault, baseInput({ slug: "first-rule" }), [inspect], {});+ expect(observed.existing).toBeNull();+ });++ test("file bytes match what writePreference would have produced (no txn overhead)", () => {+ const result = writePreferenceTxn(+ vault,+ baseInput({ slug: "bytewise-rule", principle: "exact bytes please" }),+ [],+ {},+ );+ const text = readFileSync(result.path, "utf8");+ expect(text).toContain("principle: exact bytes please");+ expect(text).toContain("kind: brain-preference");+ expect(text).toContain("_status: unconfirmed");+ });+});diff --git a/tests/core/brain/review-candidates.test.ts b/tests/core/brain/review-candidates.test.tsnew file mode 100644index 00000000..df036521--- /dev/null+++ b/tests/core/brain/review-candidates.test.ts@@ -0,0 +1,68 @@+/**+ * `buildReviewCandidates` - read-only projection over what the next+ * dream pass would do. The helper drives `dream({ dryRun: true })`+ * so no persistent state mutates between invocations.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { dreamRunsDir } from "../../../src/core/brain/paths.ts";+import { buildReviewCandidates } from "../../../src/core/brain/review-candidates.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-rc-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-rc-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++describe("buildReviewCandidates", () => {+ test("returns a frozen report with all six top-level fields", () => {+ const r = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });+ expect(Object.isFrozen(r)).toBe(true);+ expect(Array.isArray(r.would_create)).toBe(true);+ expect(Array.isArray(r.would_promote)).toBe(true);+ expect(Array.isArray(r.would_retire)).toBe(true);+ expect(Array.isArray(r.would_supersede)).toBe(true);+ expect(Array.isArray(r.clusters_below_threshold)).toBe(true);+ expect(Array.isArray(r.gated_retires)).toBe(true);+ });++ test("returns empty arrays on a fresh-bootstrap vault", () => {+ const r = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });+ expect(r.would_create).toEqual([]);+ expect(r.would_promote).toEqual([]);+ expect(r.would_retire).toEqual([]);+ expect(r.would_supersede).toEqual([]);+ expect(r.clusters_below_threshold).toEqual([]);+ expect(r.gated_retires).toEqual([]);+ });++ test("does NOT create a workrun file (dry-run path)", () => {+ buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });+ const dir = dreamRunsDir(vault);+ if (existsSync(dir)) {+ const entries = readdirSync(dir);+ expect(entries).toEqual([]);+ }+ });++ test("invoked twice in a row produces identical output (idempotent)", () => {+ const a = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });+ const b = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });+ expect(JSON.stringify(a)).toBe(JSON.stringify(b));+ });+});diff --git a/tests/core/brain/sync-lockfile.test.ts b/tests/core/brain/sync-lockfile.test.tsnew file mode 100644index 00000000..9fa27f55--- /dev/null+++ b/tests/core/brain/sync-lockfile.test.ts@@ -0,0 +1,118 @@+/**+ * Sync lockfile primitive for the brain write path. Single-attempt+ * exclusive create via `fs.openSync(target + '.lock', 'wx')`. Collisions+ * surface as a regular Error with `.code === 'ELOCKED'`; the brain+ * txn layer maps that to a `BrainCollisionError({ kind: 'SourceLock' })`.+ */++import { afterAll, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ acquireLockSync,+ scanStaleLocks,+} from "../../../src/core/brain/sync-lockfile.ts";++let tmpRoot: string;++beforeEach(() => {+ tmpRoot = mkdtempSync(join(tmpdir(), "osb-sync-lock-"));+});++afterAll(() => {+ if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });+});++describe("acquireLockSync", () => {+ test("creates a .lock sibling file and release removes it", () => {+ const target = join(tmpRoot, "pref-foo.md");+ writeFileSync(target, "---\nkind: brain-preference\n---\n");++ const handle = acquireLockSync(target);+ expect(handle.path).toBe(target + ".lock");+ expect(existsSync(target + ".lock")).toBe(true);++ handle.release();+ expect(existsSync(target + ".lock")).toBe(false);+ });++ test("throws Error with code ELOCKED when the lock is already held", () => {+ const target = join(tmpRoot, "pref-bar.md");+ writeFileSync(target, "---\nkind: brain-preference\n---\n");++ const first = acquireLockSync(target);+ try {+ let caught: unknown;+ try {+ acquireLockSync(target);+ } catch (err) {+ caught = err;+ }+ expect(caught).toBeInstanceOf(Error);+ expect((caught as NodeJS.ErrnoException).code).toBe("ELOCKED");+ } finally {+ first.release();+ }+ });++ test("after release, target is acquirable again", () => {+ const target = join(tmpRoot, "pref-baz.md");+ writeFileSync(target, "---\n---\n");++ const first = acquireLockSync(target);+ first.release();+ const second = acquireLockSync(target);+ expect(existsSync(target + ".lock")).toBe(true);+ second.release();+ });++ test("release is idempotent (second call is a no-op)", () => {+ const target = join(tmpRoot, "pref-idem.md");+ writeFileSync(target, "");+ const handle = acquireLockSync(target);+ handle.release();+ handle.release(); // must not throw+ expect(existsSync(target + ".lock")).toBe(false);+ });++ test("acquire creates the lock even when the target file does not exist", () => {+ // The brain txn path needs to be able to lock the target before the+ // file is created (first-time write). The lock primitive must not+ // require the target to exist.+ const target = join(tmpRoot, "pref-new.md");+ const handle = acquireLockSync(target);+ try {+ expect(existsSync(target + ".lock")).toBe(true);+ expect(existsSync(target)).toBe(false);+ } finally {+ handle.release();+ }+ });+});++describe("scanStaleLocks", () => {+ test("returns paths of every .lock file under the given root", () => {+ const a = join(tmpRoot, "pref-a.md");+ const b = join(tmpRoot, "sub", "pref-b.md");+ writeFileSync(a, "");+ const ha = acquireLockSync(a);+ // Manually drop a lock under a subdirectory to exercise the walk.+ const subDir = join(tmpRoot, "sub");+ require("node:fs").mkdirSync(subDir, { recursive: true });+ writeFileSync(b + ".lock", "");++ const found = scanStaleLocks(tmpRoot).sort();+ expect(found).toContain(a + ".lock");+ expect(found).toContain(b + ".lock");++ ha.release();+ require("node:fs").unlinkSync(b + ".lock");+ });++ test("returns an empty array when no locks exist", () => {+ const found = scanStaleLocks(tmpRoot);+ expect(found).toEqual([]);+ });+});diff --git a/tests/mcp/brain-review-candidates.test.ts b/tests/mcp/brain-review-candidates.test.tsnew file mode 100644index 00000000..6fc394f5--- /dev/null+++ b/tests/mcp/brain-review-candidates.test.ts@@ -0,0 +1,58 @@+/**+ * `brain_review_candidates` MCP tool wiring. Exercises the tool+ * through the same path the MCP server uses: tool lookup, handler+ * invocation, response shape.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { BRAIN_TOOLS } from "../../src/mcp/brain-tools.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;+// Minimal shape - the brain_review_candidates handler only reads+// `ctx.vault`. We construct a structural match and cast to the+// handler's parameter type at the call site.+let ctx: { vault: string; configPath: string };++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-rc-mcp-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-rc-mcp-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath };+});+afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++describe("brain_review_candidates MCP tool", () => {+ test("is registered in BRAIN_TOOLS", () => {+ const tool = BRAIN_TOOLS.find((t) => t.name === "brain_review_candidates");+ expect(tool).toBeDefined();+ expect(tool?.description).toContain("preview");+ expect(tool?.inputSchema).toBeDefined();+ });++ test("returns the six fields, all empty on a fresh vault", async () => {+ const tool = BRAIN_TOOLS.find((t) => t.name === "brain_review_candidates");+ expect(tool).toBeDefined();+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ const out = (await tool!.handler(ctx as any, {+ now: "2026-05-27T12:00:00Z",+ })) as Record<string, unknown>;+ expect(out["would_create"]).toEqual([]);+ expect(out["would_promote"]).toEqual([]);+ expect(out["would_retire"]).toEqual([]);+ expect(out["would_supersede"]).toEqual([]);+ expect(out["clusters_below_threshold"]).toEqual([]);+ expect(out["gated_retires"]).toEqual([]);+ });+});diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.tsindex 0cc6eba8..716e0eea 100644--- a/tests/mcp/mcp.test.ts+++ b/tests/mcp/mcp.test.ts@@ -165,6 +165,7 @@ describe("tool listing", () => {// brain_daily_brief / brain_weekly_synthesis added in v0.10.18)."brain_feedback","brain_dream",+ "brain_review_candidates","brain_apply_evidence","brain_note","brain_context",@@ -381,11 +382,12 @@ describe("stdio loop", () => {const list = JSON.parse(lines[1]!);expect(init.id).toBe(1);expect(list.id).toBe(2);- // v0.10.18: 3 core + 19 Brain (brain_timeline /+ // v0.12.0: 3 core + 20 Brain (brain_review_candidates added in+ // v0.12.0 Brain Integrity Suite, brain_timeline /// brain_belief_evolution / brain_stale_scan / brain_daily_brief /// brain_weekly_synthesis added v0.10.18)- // + 8 Pay Memory + 1 Search = 31.- expect(list.result.tools.length).toBe(31);+ // + 8 Pay Memory + 1 Search = 32.+ expect(list.result.tools.length).toBe(32);});test("returns parse error for invalid JSON", async () => {