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.9.0: Brain β observing memory layer for agent preferences
Sol Aitken3603c6fe6087
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex be86d3e1..bbb6c5e8 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.8.1",+ "version": "0.9.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 dc884072..81d82fb6 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.8.1",+ "version": "0.9.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 ce6ebfaa..c50f29d7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,125 @@ 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.9.0] - 2026-05-15++Brain: a new top-level vault layer for observing, accreting memory.+Agents record taste signals from conversation and per-artifact+evidence of preference application; a deterministic `dream` pass+turns repeat signals into rules whose confidence grows from real use+and decays when nothing applies them. Filesystem-first, Obsidian-+native, no LLM inside the algorithm β counters, thresholds, atomic+file operations only. Conceptually mirrors Anthropic's *Dreaming*+research preview (2026-05-06) but stays runtime-agnostic and+deterministic.++The previous agent-facing write paths (`event_log_append` and+`second_brain_capture` MCP tools, the `agent-event-log` skill) are+soft-deprecated in v0.9.0: the handlers remain in the codebase and+the CLI counterparts (`o2b append-event`, `vault-log`) keep working+for humans on the shell, but agents through the plugin surface no+longer see them. Brain replaces them as the writable surface.++Pay Memory is **unchanged** in v0.9.0 β it remains agent-visible as+an orthogonal audit layer for paid actions.++### Added++- **Brain layer** at top-level `Brain/` directory in the vault.+ Subdirectories: `inbox/`, `preferences/`, `retired/`, `log/`,+ `.snapshots/`. Plus `_brain.yaml` (schema-versioned config with+ thresholds for `candidate_threshold`, `unconfirmed_window_days`,+ `contradiction_window_days`, `stale_evidence_days`,+ `high_freshness_factor`, `snapshots.retention_count`) and+ `_BRAIN.md` (agent-facing operating manual, rendered by `o2b+ brain init`, kept under 200 lines).+- **CLI namespace `o2b brain *`** with 11 verbs: `init`,+ `feedback`, `dream`, `apply-evidence`, `digest`, `query`,+ `reject`, `pin`, `unpin`, `rollback`, `doctor`.+- **MCP tool namespace `brain_*`** with 6 tools: `brain_feedback`,+ `brain_dream`, `brain_apply_evidence`, `brain_digest`,+ `brain_query`, `brain_doctor`. `init`, `reject`, `pin`, `unpin`,+ `rollback` are intentionally CLI-only (admin / destructive+ operations are not exposed to autonomous agents).+- **Pre-run snapshots**: each `dream` run that mutates state writes+ `Brain/.snapshots/<run_id>.tar.zst` of the entire `Brain/` tree+ (excluding `.snapshots/` itself) before any mutation. Retention+ is configurable in `_brain.yaml` (default 10 most-recent).+ `o2b brain rollback <run_id>` restores from a snapshot.+- **Pin protection**: preferences marked `pinned: true` are exempt+ from automatic retirement (`stale-no-evidence`,+ `expired-unconfirmed`, `rebutted`). Only `o2b brain reject` can+ retire a pinned preference (with an extra warning). CLI verbs+ `o2b brain pin` and `o2b brain unpin` toggle the flag; both are+ CLI-only β the MCP surface intentionally does not expose them.+- **Skill `brain-memory`** (`skills/brain-memory/SKILL.md`):+ instructs agents when to call `brain_feedback` (taste signals+ from dialogue) and `brain_apply_evidence` (per durable artifact).+ Loaded automatically alongside the existing `open-second-brain`+ skill.+- **Brain digest**: `o2b brain digest` renders a Markdown or JSON+ summary of new unconfirmed preferences, confirmations,+ retirements, confidence shifts, and contradictions in a window.+ Exit code `2` when empty and `--silent-if-empty` is set β fits+ Hermes cron `--no-agent --script` jobs cleanly. Recipe in+ [`docs/hermes-cron.md`](docs/hermes-cron.md).++### Changed++- **`AI Wiki/_OPEN_SECOND_BRAIN.md`** is now overwritten by+ `o2b brain init` to a Brain-first operating manual; the file+ previously described agent-owned write conventions for+ `AI Wiki/` itself. With approximately zero non-author users at+ this stage no backup of the prior file is taken β by design.+- **`hooks/lib/messages.ts` PostToolUse reminder** rewritten:+ no longer references `event_log_append`. Points the agent at+ `brain_feedback` (when the turn contained a user preference)+ and `brain_apply_evidence` (when an active preference scopes+ to the artifact just produced).+- **`skills/open-second-brain/SKILL.md`** body rewritten to+ describe the three-layer model (`Brain/` writable, `AI Wiki/` ++ `Daily/` read-only, Pay Memory orthogonal). Cross-references+ the new `brain-memory` skill.++### Removed (from agent-facing surface; handlers retained in code)++- **`Stop` lifecycle hook** that previously blocked the turn once+ on missing `event_log_append`. The entry is removed from+ `hooks/hooks.json`; the handler file+ `hooks/stop-log-guardrail.ts` remains in the codebase. No+ Brain-specific Stop guardrail is added in v0.9.0 β the+ PostToolUse reminder is the only nudge.++### Deprecated (agent-facing only, code and CLI retained)++- **MCP tool `event_log_append`** β no longer in the advertised+ tool list returned by `src/mcp/tools.ts`. Handler stays on disk.+ The CLI counterparts `o2b append-event` and `vault-log` remain+ fully functional for human shell use.+- **MCP tool `second_brain_capture`** β same pattern: removed+ from advertisement, handler retained.+- **Skill `agent-event-log`** moved to `docs/legacy-skills/` so+ the runtime skill scanner stops loading it. The Markdown remains+ accessible as documentation.++### Notes++- Pay Memory is unchanged. All 11 Pay Memory CLI commands and+ 8 MCP tools work exactly as in v0.8.1.+- `AI Wiki/` and `Daily/` remain on disk and stay readable for+ agents via `second_brain_query`. Agents do not write to them+ in v0.9.0+.+- OpenClaw native JavaScript parity for Brain tools is deferred+ to v0.9.1 (tracked as BRAIN-FUT-007 in+ [`docs/plans/2026-05-15-brain-roadmap.md`](docs/plans/2026-05-15-brain-roadmap.md)).+ v0.9.0 ships Brain through the TypeScript CLI + MCP path used by+ Hermes, Claude Code, and Codex.+- Hard removal of the deprecated v0.8.x agent-facing write code+ is deferred to v0.10 or later, gated on observed usage of Brain+ (BRAIN-FUT-009).+- Full design and implementation plan:+ [`docs/plans/2026-05-15-brain-observing-memory.md`](docs/plans/2026-05-15-brain-observing-memory.md).+## [0.8.1] - 2026-05-14Plugin-bundled lifecycle hooks for Claude Code and Codex that close adiff --git a/README.md b/README.mdindex 8f9ce7f8..f07e00e1 100644--- a/README.md+++ b/README.md@@ -3,37 +3,45 @@A filesystem-first, agent-owned second brain for Obsidian-compatibleMarkdown vaults. Plugs into the agent runtime you already use β HermesAgent, Claude Code, OpenAI Codex, OpenClaw, or any MCP-aware client β-and gives it deterministic CLI / MCP / hook surfaces for vault setup,-daily event logging, wiki indexing, paid-action audit, and health-checks. The model never has to guess at any of that.+and gives it deterministic CLI / MCP / hook surfaces for observing+memory (preference accretion via the `Brain/` layer), wiki indexing,+paid-action audit, and health checks. The model never has to guess at+any of that.-Open Second Brain is **not** a daemon, **not** a vault replacement, and-never writes hidden state outside the configured vault and config-directory.+Open Second Brain is **not** a daemon, **not** a vault replacement,+and **not** an LLM-driven knowledge store β the `dream` consolidation+pass is pure deterministic counters. The plugin never writes hidden+state outside the configured vault and config directory.## Supported runtimes| Runtime | Integration | Notes || --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ || Hermes Agent | Hermes plugin (`plugin.yaml`) + MCP server | Adds a per-turn identity reminder via the `pre_llm_call` hook. |-| Claude Code | Marketplace plugin + bundled `.mcp.json` + lifecycle hooks | `hooks/hooks.json` registers `PostToolUse` reminder + `Stop` guardrail (see [`hooks/`](hooks/)). |+| Claude Code | Marketplace plugin + bundled `.mcp.json` + lifecycle hooks | `hooks/hooks.json` registers a `PostToolUse` reminder that points the agent at `brain_feedback` / `brain_apply_evidence` after every Write/Edit. See [`hooks/`](hooks/). || OpenAI Codex | Marketplace plugin + MCP server + lifecycle hooks | Same hook bundle as Claude Code. |-| OpenClaw | Native JS plugin (`openclaw.extensions`) β no MCP needed | The five core tools are registered directly inside OpenClaw's Node.js process. |+| OpenClaw | Native JS plugin (`openclaw.extensions`) β no MCP needed | Core query/status/health tools are registered directly inside OpenClaw's Node.js process. Native parity with the `brain_*` tools is tracked separately in the post-v0.9 roadmap. || Other MCP hosts | Generic adapter (stdio MCP server, persisted plugin config) | See `install.md` branch E for the contract. |## What it does-- Bootstraps an agent-owned area inside your vault β `AI Wiki/`- plus `_OPEN_SECOND_BRAIN.md`.-- Appends agent events to daily Markdown notes- (`Daily/YYYY.MM.DD.md`, append-only below `## Raw events`).-- Regenerates a Markdown page index from frontmatter and wikilinks.-- Exports config snapshots with secret-like values redacted.-- Runs vault + adapter health checks (`o2b doctor`).+- Bootstraps `Brain/` β the observing-memory layer where the agent+ records taste signals, accreted preferences, evidence, and+ pre-run snapshots.+- Runs a deterministic `dream` pass that turns repeat signals into+ confirmed rules, retires stale ones, and surfaces contradictions+ β no LLM inside the algorithm, only counters, thresholds, and+ atomic file operations. See [Brain section](#brain-observing-memory).+- Regenerates a Markdown page index from frontmatter and wikilinks+ (`o2b index`).+- Exports config snapshots with secret-like values redacted+ (`o2b export-config`).+- Runs vault + adapter health checks (`o2b doctor`, plus+ `o2b brain doctor` for Brain-specific invariants).- (Optional) Records paid agent actions through **Pay Memory**:receipts, generated assets, spending policy decisions, human- approval state, and per-day reports β all as plain Markdown inside- the vault.+ approval state, and per-day reports β all as plain Markdown+ inside the vault.## Install@@ -70,15 +78,26 @@ After `o2b install-cli` the following commands are on PATH:```texto2b status Show config / vault statuso2b init Bootstrap the vault profile (idempotent)-o2b install-cli Symlink o2b, vault-log, o2b-hook into ~/.local/bin+o2b install-cli Symlink o2b and o2b-hook into ~/.local/bino2b doctor Run vault + adapter checks-o2b append-event Append one daily event-log entryo2b index Rebuild the Markdown page indexo2b export-config Write a redacted config snapshot-o2b mcp Run the optional MCP tool server (stdio)+o2b mcp Run the MCP tool server (stdio)o2b tool-call Invoke an MCP tool handler from the CLIo2b uninstall Print uninstall plan; --apply-local cleans config; --remove-cli removes symlinks+# Brain (observing memory β 11 verbs)+o2b brain init Bootstrap Brain/{inbox,preferences,retired,log,.snapshots}/ + _brain.yaml + _BRAIN.md+o2b brain feedback Record one taste signal (--topic, --signal, --principle, ...)+o2b brain dream Run the deterministic consolidation pass (idempotent; usually cron'd)+o2b brain apply-evidence Record applied / violated against a preference for a durable artifact+o2b brain digest Render a Markdown or JSON summary of recent Brain transitions+o2b brain query Read helper: by preference, by topic, or by log timestamp+o2b brain reject (CLI-only) Move a preference to retired/ with reason: user-rejected+o2b brain pin / unpin (CLI-only) Toggle pinned: true on a preference (exempt from auto-retire)+o2b brain rollback (CLI-only) Restore Brain/ from a pre-dream snapshot+o2b brain doctor Check Brain-specific invariants (status-vs-folder, broken wikilinks, β¦)+# Pay Memoryo2b init-pay-memory Bootstrap AI Wiki/{policies,payments,assets,drafts,reports}/o2b append-payment-receipt Save a Markdown receipt for a paid API call@@ -93,7 +112,6 @@ o2b list-pending-payments List pending / approved / etc. requestso2b payment-digest Render a 4-line digest for a date# Helpers-vault-log Compatibility wrapper around `o2b append-event`o2b-hook Internal launcher invoked by hooks/hooks.json (Claude Code & Codex)```@@ -105,8 +123,12 @@ The local checkout can also be used without installing the symlinksThe plugin ships an optional stdio MCP server (`o2b mcp`) thatexposes the same deterministic operations as MCP tools:-- **Core (5):** `second_brain_status`, `second_brain_query`,- `second_brain_capture`, `event_log_append`, `vault_health`.+- **Core (3):** `second_brain_status`, `second_brain_query`,+ `vault_health`.+- **Brain (6):** `brain_feedback`, `brain_dream`,+ `brain_apply_evidence`, `brain_digest`, `brain_query`,+ `brain_doctor`. See the [Brain section](#brain-observing-memory)+ below.- **Pay Memory (8):** `payment_memory_init`,`payment_receipt_append`, `asset_capture`,`payment_report_generate`, `payment_policy_check`,@@ -123,23 +145,69 @@ schemas, and lifecycle details are in [`docs/mcp.md`](docs/mcp.md).## Lifecycle hooks (Claude Code & Codex)The plugin bundles a `hooks/hooks.json` that both runtimes auto-load.-Two hooks fire per turn:+One hook fires per turn:- **PostToolUse** (matcher `Write|Edit|MultiEdit|apply_patch`) β- after a file-mutating tool succeeds, injects a short reminder that- the agent should call `event_log_append` if the change is a- durable artifact.-- **Stop** β when the runtime is about to end the turn, parses the- transcript JSONL, and if a durable-looking artifact was produced- without a matching log call, blocks the Stop **once** with- `decision: "block"`. The next Stop passes unconditionally, so the- agent can deliberately skip logging on trivial edits by just- finishing again. No deadlocks.--This was added to close the gap exposed by a real bug where soft-MCP-server instructions were silently dropped under load.+ after a file-mutating tool succeeds, injects a short reminder+ pointing the agent at `brain_feedback` (when the turn contained a+ user preference or correction) and `brain_apply_evidence` (when an+ active preference in `Brain/preferences/` scopes to the artifact+ just produced).+Hermes and OpenClaw don't load these hooks β they have their own-per-turn channels. Full design notes: [`hooks/README.md`](hooks/README.md).+per-turn channels. Full design notes:+[`hooks/README.md`](hooks/README.md).++## Brain (observing memory)++Brain is the agent-writable observing-memory layer. Agents record+user preferences as raw taste signals; a deterministic `dream` pass+accretes repeat signals into rules with confidence that grows from+real applications and decays when nothing applies the rule any more.+There is no LLM inside the algorithm β only counters, thresholds,+and `mv` operations.++```bash+o2b brain init --vault /path/to/vault+# β Brain/{inbox,preferences,retired,log,.snapshots}/ plus _brain.yaml and _BRAIN.md++# Record a taste signal (agent or human, mid-conversation):+o2b brain feedback \+ --vault /path/to/vault \+ --topic no-internal-abbrev --signal negative \+ --principle "Do not use internal abbreviations in user-facing copy unless explained first" \+ --agent claude++# After producing a durable artifact, record evidence:+o2b brain apply-evidence \+ --vault /path/to/vault \+ --pref pref-no-internal-abbrev \+ --artifact "[[Daily/2026.05.14#section-blog-post]]" \+ --result applied --agent claude++# Run a dream pass (cron or manual): promotes candidates, retires stale rules:+o2b brain dream --vault /path/to/vault++# Short daily summary (markdown or JSON), suitable for Hermes cron β Telegram:+o2b brain digest --vault /path/to/vault --silent-if-empty+```++Eleven CLI verbs in total: `init`, `feedback`, `dream`,+`apply-evidence`, `digest`, `query`, `reject`, `pin`, `unpin`,+`rollback`, `doctor`. Six are mirrored as MCP tools (`brain_*`);+`init`, `reject`, `pin`, `unpin`, `rollback` are intentionally+CLI-only because they change the protected set or overwrite vault+state. Pre-run snapshots of `Brain/` go to `Brain/.snapshots/` and+support `o2b brain rollback <run_id>`. Pinned preferences are exempt+from automatic retire (`stale-no-evidence`, `expired-unconfirmed`,+`rebutted`); only `o2b brain reject` can retire them.++Full design and implementation plan:+[`docs/plans/2026-05-15-brain-observing-memory.md`](docs/plans/2026-05-15-brain-observing-memory.md).+Post-v0.9 trigger-based roadmap:+[`docs/plans/2026-05-15-brain-roadmap.md`](docs/plans/2026-05-15-brain-roadmap.md).+The `brain-memory` skill (loaded automatically) instructs agents when+to call `brain_feedback` and `brain_apply_evidence`.## Pay Memory@@ -350,8 +418,13 @@ you want to.optional MCP server is a stdio subprocess that exits when itsparent runtime exits.- Hooks (Claude Code, Codex) only inject text into the agent's- context. They never write to the vault directly β every log- entry still goes through `event_log_append` or the equivalent CLI.+ context. They never write to the vault directly β every Brain+ entry goes through `brain_feedback` / `brain_apply_evidence`+ (MCP) or the equivalent CLI (`o2b brain *`).+- Brain mutations (`o2b brain dream`) take an automatic pre-run+ snapshot (`Brain/.snapshots/<run_id>.tar.zst`) before any state+ change. `o2b brain rollback <run_id>` restores from a snapshot;+ retention is configurable in `_brain.yaml`.## Repositorydiff --git a/docs/architecture.md b/docs/architecture.mdindex e9c44b19..ecbe6330 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -200,6 +200,42 @@ AI Wiki/This layout is intentionally agent-owned. The project should not mix agent-generated wiki pages into a user's personal notes without clear boundaries.+`AI Wiki/` holds the static agent-facing wiki: identity, index, hot list, and the Pay Memory subtree (`payments/`, `assets/`, `drafts/`, `reports/`, `policies/`). Agents read it through `second_brain_query` and write into Pay Memory subdirectories via the `payment_*` tools. Durable observing memory β taste signals, accreted preferences, evidence, snapshots β lives in a separate top-level `Brain/` directory described in the next section.++## Brain layer++`Brain/` is a top-level directory parallel to `AI Wiki/` and `Daily/`. It is the observing-memory layer: where agents record taste signals, the `dream` pass accretes them into rules, and pre-run snapshots provide reversibility.++```text+Brain/+ _brain.yaml # schema + thresholds (validated by o2b brain doctor)+ _BRAIN.md # operating manual for agents (rendered by o2b brain init)+ inbox/ # raw taste signals, sig-<date>-<slug>.md+ processed/ # signals already folded into a preference+ preferences/ # active rules: pref-<slug>.md, status unconfirmed | confirmed+ retired/ # ret-<slug>.md with retired_reason+ log/ # YYYY-MM-DD.md, append-only event log (dream / apply-evidence / etc.)+ .snapshots/ # <run_id>.tar.zst, pre-run snapshots for o2b brain rollback+```++Three architectural invariants:++- **Filesystem-first.** No database, no daemon. Every artifact is plain Markdown with YAML frontmatter; backup is `cp -r` or `tar`.+- **Deterministic core.** The `dream` algorithm is a pure function of inputs (signals, preferences, log, configuration, current time). No LLM calls inside the core. Semantic merging, if needed, is delegated to external agents via the same CLI / MCP surface.+- **Pre-run snapshot + atomic per-file writes.** Each `dream` run takes a `.snapshots/<run_id>.tar.zst` before any state change; per-file writes go through `fs-atomic` (temp + rename). Combined with retention of the most-recent N snapshots, this gives reversible, audit-friendly mutation.++The layered diagram from the top of this document still holds β `Brain/` sits at the same level as the vault files in the bottom layer:++```text+Agent runtime+ -> runtime adapter/plugin+ -> skills and commands (brain-memory skill, open-second-brain skill)+ -> CLI/core library (src/core/brain/*)+ -> vault files: Brain/ (observing memory), AI Wiki/ + Daily/ (wiki + event log), Pay Memory (paid-action audit)+```++Full design: [`docs/plans/2026-05-15-brain-observing-memory.md`](plans/2026-05-15-brain-observing-memory.md).+## Event logThe event log is append-only. It records operational events, not polished knowledge.diff --git a/docs/hermes-cron.md b/docs/hermes-cron.mdindex db0e45c9..45e78bbd 100644--- a/docs/hermes-cron.md+++ b/docs/hermes-cron.md@@ -64,3 +64,80 @@ When there were no receipts the day before, the literal token `[SILENT]` is emit## Standalone shell wrapper (optional)If you'd rather invoke this from systemd, GitHub Actions, or any non-Hermes scheduler, see [`examples/hermes-payment-digest.sh`](../examples/hermes-payment-digest.sh) β a thin Bash wrapper around `o2b payment-digest` that takes the vault path as `$1`.++---++# Hermes cron β daily Brain digest++`o2b brain digest` renders a short Markdown summary of what the `dream` pass did over a given window: new unconfirmed preferences, confirmations, retirements, confidence shifts, and contradictions. The same wiring as the Pay Memory digest above β `--no-agent --script` ships the markdown verbatim, `--silent-if-empty` suppresses delivery when nothing changed.++## Prerequisites++Same as the Pay Memory digest: Hermes installed, the plugin enabled, `o2b` on `PATH`, vault path known, and a Telegram destination. Additionally, `o2b brain init --vault <path>` must have been run once on the target vault so `Brain/_brain.yaml` exists.++## Register the cron job++The example below fires at 20:00 UTC daily and reports the trailing 24 hours of `Brain/log/`:++```bash+hermes cron create \+ --name "brain-digest-daily" \+ --deliver "telegram:<chat_id>:<topic_id>" \+ --workdir "/" \+ --no-agent --script \+ '0 20 * * *' \+ 'o2b brain digest --vault /path/to/vault --silent-if-empty'+```++Notes:++- `--no-agent --script` makes Hermes shell out to the command and deliver its stdout verbatim. `cron.wrap_response: false` (default Hermes config) keeps the framing clean.+- `--silent-if-empty` produces no output AND exits with code `2` when nothing changed in the window; Hermes treats the empty stdout as a no-op and does not push a Telegram message.+- The default window is the trailing 24h. Use `--since <ISO>` / `--until <ISO>` to override.+- Run frequency is up to you; `dream` is idempotent, so a higher-frequency digest does not produce duplicate noise β it only reports new transitions.++## Run, edit, pause, remove++```bash+hermes cron list+hermes cron run brain-digest-daily # one-shot dry run+hermes cron edit brain-digest-daily --schedule '0 19 * * *'+hermes cron pause brain-digest-daily+hermes cron resume brain-digest-daily+hermes cron remove brain-digest-daily+```++## What the digest looks like++```markdown+# Brain digest β 2026-05-14T20:00Z (24h)++## New (unconfirmed, in trial)++- [[pref-no-internal-abbrev]] β writing, 3 signals, trial ends 2026-05-28+- [[pref-imperative-prompts]] β coding, 4 signals, trial ends 2026-05-28++## Confirmed++- [[pref-prefer-typed-errors]] β coding, first applied in [[Daily/2026.05.14]]++## Retired++- [[ret-prefer-bullets-over-prose]] β writing, stale-no-evidence (91 days)++## Confidence shifts++- [[pref-no-internal-abbrev]] medium β high (applied: 11, violated: 0)+```++When `--silent-if-empty` is set and the window has no changes, the command writes nothing to stdout and exits `2` β Hermes posts nothing to the Telegram topic on those days.++## Pairing with the dream pass++`o2b brain digest` is read-only and never runs `dream` on its own. If you want a single nightly job that *first* consolidates and *then* posts the digest, chain them:++```bash+'o2b brain dream --vault /path/to/vault >/dev/null && o2b brain digest --vault /path/to/vault --silent-if-empty'+```++`dream` is itself idempotent β running it on top of an unchanged Brain is a no-op (no log entry written, no snapshot taken). The chained form is safe at any cadence.diff --git a/docs/how-it-works.md b/docs/how-it-works.mdnew file mode 100644index 00000000..2b923b36--- /dev/null+++ b/docs/how-it-works.md@@ -0,0 +1,441 @@+# How Open Second Brain Works++A working guide for engineers and agents to the mechanics of the+observing memory layer. Read this when you want to understand what the+system does, not what to configure.++## Mental model++Open Second Brain accumulates **preferences** and learns from real+usage. Three responsibilities:++- **Capture.** Agents and humans drop taste signals into `Brain/inbox/`.+- **Accretion.** A deterministic `dream` pass turns repeat signals into+ rules.+- **Application.** Agents record whether they applied or violated each+ rule when producing durable artifacts.++The LLM lives outside the system: agents use it to detect signals in+conversation and to apply rules during work. The system uses counters,+thresholds, and atomic file operations β no LLM inside the algorithm,+no surprise, no hallucinated memory.++## Vault layout++The vault holds three top-level agent-facing directories. Brain owns+its own.++```text+<vault>/+βββ Brain/ # observing memory (agent-writable)+β βββ _brain.yaml # schema, thresholds, retention+β βββ _BRAIN.md # operating manual for agents+β βββ inbox/ # raw taste signals+β β βββ sig-<date>-<slug>.md+β β βββ processed/ # signals already folded into rules+β βββ preferences/ # active rules+β β βββ pref-<slug>.md # status: unconfirmed | confirmed+β βββ retired/ # archived rules+β β βββ ret-<slug>.md # retired_reason: stale-no-evidence | expired-unconfirmed | rebutted | user-rejected+β βββ log/ # daily event log+β β βββ YYYY-MM-DD.md # append-only, typed events+β βββ .snapshots/ # pre-dream snapshots+β βββ dream-<run-id>.tar.zst+β+βββ AI Wiki/ # curated knowledge surface+β βββ identity/ # user.md, agents.md+β βββ index.md / hot.md+β βββ payments/ / assets/ / drafts/ / reports/ / policies/ β Pay Memory subtree+β βββ system/ # config snapshots, etc.+β+βββ Daily/ # chronological event log + human narrative+ βββ YYYY.MM.DD.md+```++```mermaid+flowchart LR+ Agent[Agent / MCP client]+ subgraph Vault+ Brain[Brain/]+ Wiki[AI Wiki/]+ Daily[Daily/]+ PayMem[(Pay Memory subtree<br/>under AI Wiki/)]+ end++ Agent -- "brain_* (read + write)" --> Brain+ Agent -- "second_brain_query (read)" --> Wiki+ Agent -- "second_brain_query (read)" --> Daily+ Agent -- "payment_* (read + write)" --> PayMem+```++`Brain/` is the only area where the agent records its observing+memory. `AI Wiki/` and `Daily/` are read surfaces for the agent (the+Pay Memory subtree under `AI Wiki/` is the exception: agents write+there through the `payment_*` tools).++## A preference's lifecycle++A preference moves between four states from first signal to retirement:++```mermaid+stateDiagram-v2+ [*] --> Inbox: brain_feedback+ Inbox --> Unconfirmed: dream (β₯candidate_threshold<br/>same-sign signals on topic)+ Unconfirmed --> Confirmed: brain_apply_evidence applied<br/>(first such event)+ Unconfirmed --> Retired_Expired: dream (now > unconfirmed_until,<br/>no applied evidence)+ Confirmed --> Retired_Stale: dream (last_evidence_at<br/>older than stale_evidence_days)+ Confirmed --> Retired_Rebutted: dream (β₯candidate_threshold<br/>opposite-sign signals collected)+ Confirmed --> Retired_UserRejected: o2b brain reject+ Unconfirmed --> Retired_UserRejected: o2b brain reject+ Retired_Expired --> [*]+ Retired_Stale --> [*]+ Retired_Rebutted --> [*]+ Retired_UserRejected --> [*]++ note right of Confirmed+ Pinned preferences (pinned: true)+ skip all three automatic retire+ transitions. Only o2b brain reject+ can retire them.+ end note+```++`Inbox` is not really a state of the preference β it's the staging+area for the signals that will eventually create one. The first real+state is `Unconfirmed`: the rule exists but has not yet been applied+in real work.++## End-to-end signal β rule flow++A typical sequence from a user remark to a confirmed preference:++```mermaid+sequenceDiagram+ autonumber+ participant User+ participant Agent+ participant MCP as MCP layer+ participant Core as Brain core+ participant Vault++ User->>Agent: do not use internal abbreviations+ Agent->>MCP: brain_feedback (topic, signal negative, principle, agent)+ MCP->>Core: writeSignal+ Core->>Vault: atomic write Brain/inbox/sig file+ Core->>Vault: append Brain/log/today.md feedback event+ MCP-->>Agent: signal_path and signal_id+ Agent-->>User: confirmation++ Note over Vault: days pass and two more matching signals arrive on the same topic++ Note over Core: scheduled dream pass (cron or manual)+ Core->>Vault: scan inbox, preferences, log+ Core->>Core: group signals by topic+ Core->>Vault: createSnapshot to .snapshots/dream-run.tar.zst+ Core->>Vault: write Brain/preferences/pref file status unconfirmed+ Core->>Vault: move inbox signals into inbox/processed+ Core->>Vault: append log dream event+ Core->>Vault: pruneSnapshots to retention_count++ Note over Agent,User: later the agent produces a blog draft++ Agent->>Agent: write durable artifact+ Agent->>MCP: brain_apply_evidence (pref_id, artifact, result applied, agent)+ MCP->>Core: appendApplyEvidence+ Core->>Vault: append log apply-evidence event+ MCP-->>Agent: logged_at and log_path++ Note over Core: next dream pass+ Core->>Vault: scan log and count applied or violated per pref+ Core->>Vault: pref file status unconfirmed becomes confirmed+ Core->>Vault: pref file applied_count plus one, last_evidence_at, confidence+ Core->>Vault: append log dream event with confirmed list+```++Two important properties of this flow:++- The `dream` pass is the **only** writer of state transitions+ (unconfirmed β confirmed, anything β retired). Signals and+ apply-evidence events are append-only side inputs.+- Every state change is durable on disk before `dream` returns. There+ is no in-memory buffer that could be lost on crash.++## The dream pass in detail++A single dream invocation is a deterministic pipeline:++```mermaid+flowchart TD+ Start([o2b brain dream]) --> Load[Load _brain.yaml]+ Load --> Scan[Scan inbox/, preferences/, retired/, log/]+ Scan --> Plan[Plan transitions:<br/>new unconfirmed, promotions,<br/>retires, signal moves]+ Plan --> Changed{Any changes planned?}+ Changed -- no --> NoOp([return changed: false<br/>no snapshot, no log])+ Changed -- yes --> Snap["createSnapshot to<br/>.snapshots/dream-RUNID.tar.zst"]+ Snap --> SnapErr{Snapshot OK?}+ SnapErr -- fail --> Abort([throw; no state changed])+ SnapErr -- ok --> Apply++ subgraph Apply [Apply transitions]+ direction TB+ A1[Per topic: signals β unconfirmed pref<br/>if threshold met] --> A2+ A2[Per pref: count log evidence,<br/>compute applied_count / violated_count]+ A2 --> A3{Unconfirmed with applied β₯ 1?}+ A3 -- yes --> A4[Promote to confirmed,<br/>stamp confirmed_at]+ A3 -- no --> A5+ A4 --> A5[Recompute confidence]+ A5 --> A6{Pinned?}+ A6 -- yes --> A7[Skip auto-retire,<br/>log retain-pinned]+ A6 -- no --> A8{Retire conditions?}+ A8 -- stale --> A9[Move to retired/<br/>reason: stale-no-evidence]+ A8 -- expired --> A10[Move to retired/<br/>reason: expired-unconfirmed]+ A8 -- rebutted --> A11[Move to retired/<br/>reason: rebutted]+ A8 -- none --> A12[Leave in preferences/]+ A9 --> A13+ A10 --> A13+ A11 --> A13+ A12 --> A13+ A7 --> A13+ A13[Move consumed signals to processed/]+ end++ Apply --> LogEvent["Append dream event to log/today.md"]+ LogEvent --> Prune[pruneSnapshots to retention_count]+ Prune --> Done([return changed: true with summary])+```++Key rules baked into the pipeline:++- **Threshold by dominant sign.** New unconfirmed preferences are+ created only when `candidate_threshold` (default 3) **same-sign**+ signals on one topic appear within `contradiction_window_days`.+ Mixed signals cancel and the rule does not form.+- **Pre-run snapshot before any mutation.** If snapshot fails, the run+ aborts without writing anything; safety net cannot be bypassed.+- **Idempotency.** A second dream run on unchanged inputs is a no-op:+ no snapshot, no log entry, no file modifications.+- **Corrupted YAML is tolerated.** A single unparseable signal or+ preference is logged as a `skip-corrupted-frontmatter` event; the+ rest of the run proceeds.++## Confidence formula++Confidence is computed for every active preference on every dream+pass:++```mermaid+flowchart LR+ Inputs[applied_count, violated_count,<br/>last_evidence_at, age] --> Q1+ Q1{applied β€ low_max_applied<br/>OR<br/>violated β₯ applied?}+ Q1 -- yes --> Low[low]+ Q1 -- no --> Q2{applied β₯ high_min_applied<br/>AND violated = 0<br/>AND fresh?}+ Q2 -- yes --> High[high]+ Q2 -- no --> Medium[medium]+```++Defaults from `_brain.yaml`:++- `low_max_applied: 2` β rules with two or fewer applications stay+ `low` until they prove themselves.+- `high_min_applied: 10` β high confidence requires ten clean applications.+- `high_freshness_factor: 0.8` β "fresh" means+ `now - last_evidence_at < stale_evidence_days * 0.8`.+- `stale_evidence_days: 90` β the boundary for fresh / stale.++All four are tunable per vault in `Brain/_brain.yaml`.++## CLI / MCP surface++The same operations are reachable through two channels. Read columns+are mirrored in MCP; destructive operations are CLI-only by design.++| Operation | CLI verb | MCP tool | Side effect |+|--------------------------|----------------------------|-----------------------|------------------------|+| Bootstrap layer | `o2b brain init` | β | creates `Brain/` skeleton |+| Record taste signal | `o2b brain feedback` | `brain_feedback` | writes signal + log event |+| Consolidation pass | `o2b brain dream` | `brain_dream` | mutates preferences/retired, atomic snapshot |+| Record application | `o2b brain apply-evidence` | `brain_apply_evidence`| appends log event |+| Render summary | `o2b brain digest` | `brain_digest` | read-only |+| Inspect state | `o2b brain query` | `brain_query` | read-only |+| Validate invariants | `o2b brain doctor` | `brain_doctor` | read-only |+| Retire manually | `o2b brain reject` | β (CLI-only) | moves pref β retired/ |+| Toggle pin | `o2b brain pin / unpin` | β (CLI-only) | flips `pinned` field |+| Restore snapshot | `o2b brain rollback` | β (CLI-only) | overwrites Brain/ from snapshot |++Operations that change the **protected set** (`pin`, `unpin`,+`reject`, `rollback`) are kept off the MCP surface so an autonomous+agent cannot quietly alter what is shielded from automatic retire or+roll back state.++## Snapshots and rollback++A snapshot is taken before any state-changing dream run:++```mermaid+flowchart TD+ Trigger[dream wants to mutate] --> CS[createSnapshot]+ CS -- failure --> Abort([abort; nothing changed])+ CS -- success --> Mutate[apply mutations]+ Mutate --> Log[append dream log event]+ Log --> Prune[pruneSnapshots to retention_count]++ RB["o2b brain rollback RUNID"] --> Restore[restoreSnapshot]+ Restore --> Extract[extract .tar.zst into tmp]+ Extract --> Replace[replace Brain/ entries<br/>excluding .snapshots/]+ Replace --> LogR[append rollback log event]+```++A snapshot captures every file under `Brain/` **except** `.snapshots/`+itself β otherwise rollback would erase any snapshots taken after+this one. Retention defaults to ten newest archives.++```mermaid+flowchart LR+ BrainRoot[Brain/]+ BrainRoot --> Yaml[_brain.yaml]+ BrainRoot --> Manual[_BRAIN.md]+ BrainRoot --> Inbox[inbox/]+ BrainRoot --> Prefs[preferences/]+ BrainRoot --> Ret[retired/]+ BrainRoot --> LogD[log/]+ BrainRoot --> Snaps[.snapshots/]+ Yaml --> Archive((snapshot.tar.zst))+ Manual --> Archive+ Inbox --> Archive+ Prefs --> Archive+ Ret --> Archive+ LogD --> Archive+ Snaps -. excluded .-> Archive+```++## Integration with agent runtimes++The same MCP tools are advertised to every runtime; only the wiring+differs:++```mermaid+graph LR+ Hermes -- "mcp_servers.yaml" --> Stdio["o2b mcp (stdio)"]+ ClaudeCode["Claude Code"] -- "bundled .mcp.json" --> Stdio+ Codex -- "codex mcp add" --> Stdio+ OpenClaw -- "native JS plugin" --> InProc["in-process tools"]+ Stdio --> Vault[(Brain/ on disk)]+ InProc --> Vault+```++- **Hermes** loads the MCP server via `mcp_servers:` in+ `~/.hermes/config.yaml`. The agent surface also needs the+ `brain-memory` skill enabled in the active profile (via+ `hermes-skills-sync enable <profile> brain-memory`) so the LLM+ recognises preference triggers in conversation.+- **Claude Code** picks up the bundled `.mcp.json` and the+ plugin-shipped `brain-memory/SKILL.md` automatically.+- **Codex** registers the MCP server with `codex mcp add`; the same+ skill bundle is loaded automatically.+- **OpenClaw** runs tools natively in the plugin's Node.js process+ (no subprocess, by security-scanner requirement).++## Safety properties++These are invariants of the system, not configuration to enable.++- **Filesystem-first.** Every Brain artifact is a Markdown file with+ YAML frontmatter. `cp -r Brain/` is a complete backup; `tar -czf`+ is a portable bundle.+- **Deterministic.** The dream pass is a pure function of (signals,+ preferences, retired, log, configuration, current time). Given+ identical inputs and a fixed `--now`, two runs produce byte-identical+ output.+- **Idempotent.** Re-running dream without new input or expired+ timestamps is a no-op. Safe to schedule at any frequency.+- **Atomic per-file writes.** Every mutation goes through+ write-temp + rename; an interrupted run never leaves partial files.+- **Audit-traceable.** Every state change emits a typed event in+ `Brain/log/<day>.md`. The log is append-only; the dream log entry+ for a run records exactly which preferences moved and why.+- **Reversible.** Pre-run snapshots plus+ `o2b brain rollback <run-id>` let you undo any single dream pass.+- **Path-safe.** Every writer routes through a vault-boundary check;+ `Brain/` operations cannot escape the configured vault root.+- **No LLM inside the algorithm.** Semantic merging of similar but+ differently-slugged topics is left to external agents who can call+ the CLI / MCP surface directly β the dream pass itself only does+ counting and atomic file moves.++## Sample lifecycle of one preference++A worked example spanning a hundred days of vault activity:++```mermaid+sequenceDiagram+ autonumber+ actor User+ participant Agent+ participant Brain+ participant Dream as dream pass++ User->>Agent: day 0 β "don't use internal abbreviations"+ Agent->>Brain: brain_feedback (neg, topic)+ Brain-->>Brain: sig #1 in inbox/++ User->>Agent: day 1 β same complaint+ Agent->>Brain: brain_feedback+ Brain-->>Brain: sig #2++ User->>Agent: day 3 β third complaint+ Agent->>Brain: brain_feedback+ Brain-->>Brain: sig #3 (threshold met)++ Note over Dream: day 3 dream pass+ Dream->>Brain: create pref-X status: unconfirmed<br/>(trial: 14 days)+ Dream->>Brain: move sig #1..3 β processed/++ Agent->>Agent: day 5 β produces public blog post+ Agent->>Brain: brain_apply_evidence applied++ Note over Dream: day 5 dream pass+ Dream->>Brain: pref-X status: confirmed,<br/>applied_count=1, confidence=low++ Agent->>Brain: days 6..30 β nine more applied evidences++ Note over Dream: day 30 dream pass+ Dream->>Brain: pref-X applied_count=10,<br/>confidence=high++ Note over Dream: days 31..120 β silence on this topic++ Note over Dream: day 120 dream pass (90 days past last evidence)+ Dream->>Brain: move pref-X β retired/<br/>reason: stale-no-evidence+```++At day 120 the rule has retired itself. The retired note keeps the+full origin (the three signals, the confirmation timestamp, the+ten evidence applications) so its history is auditable forever; only+the active-rule attention budget is freed.++## How a new vault gets bootstrapped++```mermaid+flowchart LR+ User[operator] --> Init([o2b brain init])+ Init --> Skel["Create Brain/inbox, preferences, retired, log, .snapshots"]+ Init --> Yaml[Render Brain/_brain.yaml with defaults]+ Init --> Manual[Render Brain/_BRAIN.md operating manual]+ Init --> Overview[Write AI Wiki/_OPEN_SECOND_BRAIN.md vault overview]+```++`Brain/_brain.yaml` defaults are sensible for most uses; tune them in+place when real usage reveals different timing. `Brain/_BRAIN.md` is+the per-vault contract for agents β agents read it at the top of any+session that interacts with this vault, and `o2b brain init --force`+re-renders it from the current template.++## Where to go next++- **`docs/architecture.md`** β layered system architecture beyond+ Brain (vault model, runtime adapters, configuration model).+- **`docs/plans/2026-05-15-brain-observing-memory.md`** β the design+ document, including the full file-format specs and test strategy.+- **`docs/plans/2026-05-15-brain-roadmap.md`** β trigger-based roadmap+ of future capabilities (`BRAIN-FUT-NNN` entries).+- **`Brain/_BRAIN.md`** (in any initialised vault) β the operating+ manual for agents working with that specific vault.diff --git a/skills/agent-event-log/SKILL.md b/docs/legacy-skills/agent-event-log/SKILL.mdsimilarity index 100%rename from skills/agent-event-log/SKILL.mdrename to docs/legacy-skills/agent-event-log/SKILL.mddiff --git a/docs/plans/2026-05-15-brain-observing-memory.md b/docs/plans/2026-05-15-brain-observing-memory.mdnew file mode 100644index 00000000..143b2aac--- /dev/null+++ b/docs/plans/2026-05-15-brain-observing-memory.md@@ -0,0 +1,942 @@+# Brain β Observing Memory Layer++Status: design+Target: Open Second Brain v0.9.0+Authors: Sergey Eroshenkov (product), Claude (drafting)++## 1. Overview++Open Second Brain prior to Brain is a deterministic storage layer: a vault, an event log, a Pay Memory audit trail. Agents write durable artifacts; the system makes them inspectable. It does not *learn* anything.++This document specifies a new layer β **Brain** β that turns the vault from a storage system into an observing one. Brain accumulates taste signals, promotes them into rules under deterministic thresholds, links rules to real applications during work, and retires rules that decay or get rebutted. The agent gets better at the user's preferences without anyone re-training a model and without a human running an admin workflow.++Brain is filesystem-first, deterministic, Obsidian-native, and isolated from the existing `AI Wiki/` and `Daily/` areas. It contains no LLM logic. Semantic merging, if needed, is delegated to external agents calling the same deterministic CLI/MCP surface.++The design is anchored in two prior arts. The internal one is the *Improvement* note (Sergey's vault, `Projects/OpenSecondBrain/Plan/2. Improvement`), which proposed nine extensions to OSB. Those proposals are folded into three deeper architectural ideas (graph of typed links, accreted truth, behaviour-evidence loop) and realised as a single primitive loop. The external anchor is Anthropic's *Dreaming* feature, announced 2026-05-06 as research preview inside Claude Managed Agents: an asynchronous dreaming pass over an agent's memory store, producing a curated layer that humans can review before deployment. Brain is the open-source, runtime-agnostic, deterministic counterpart.++## 2. Scope of v0.9.0++In scope:++- A new top-level directory `Brain/` inside the vault.+- File formats for signals, preferences (in two trial states), retired entries, and a daily log.+- A deterministic dreaming pass exposed as `o2b brain dream`.+- CLI namespace `o2b brain *` (11 verbs).+- MCP tool namespace `brain_*` (6 tools).+- One new skill `brain-memory` that instructs agents when to record signals and apply evidence.+- A short Brain-aware digest, suitable for terminal output and Hermes cron delivery to Telegram.+- Deprecation of agent-facing write paths in the legacy OSB surface (`event_log_append`, `second_brain_capture`, `agent-event-log` skill). The code stays; only the agent-facing surfaces stop advertising it.++Out of scope, deferred to follow-up releases:++- OpenClaw-native JavaScript parity for Brain tools (v0.9.1).+- Pay Memory integration with Brain (Pay Memory remains an orthogonal layer).+- Hard removal of deprecated legacy OSB write code from the pre-Brain era (v0.10 or later, decided by usage evidence).+- LLM-driven semantic merging of similar topics (intentionally out of scope; external agents may perform it via the same CLI/MCP surface).+- Hook-enforced reminders for Brain operations (added only if observed misses justify it).+- Auto-detection of preference signals from free-form conversation by the runtime itself (the skill instructs agents, but no automatic NLP heuristic ships).++## 3. Architectural Principles++These are constraints the implementation must respect, not aspirational goals.++**Filesystem-first.** Every Brain artifact is a Markdown file with YAML frontmatter. State changes are filesystem operations (write, rename, move between directories). No embedded database, no required indexing service, no daemon. Backup equals `cp -r` or `tar`.++**Deterministic.** `dream` is a pure function of inputs (signals, preferences, log, configuration, current time). Identical inputs produce byte-identical outputs. No randomness, no LLM calls, no network. This is the property that lets the system be trusted as the source of truth.++**Passive human participation.** The human never runs an approval workflow. Preferences are promoted to confirmed status when they are applied at least once in real work; they are retired when they go un-applied or when contradictory signals reach the rebuttal threshold. Optional escape hatches exist (`--force-confirmed`, `o2b brain reject`) but are not part of the default loop.++**Obsidian-native.** Cross-references are Obsidian wikilinks (`[[basename]]`). Backlinks and graph view work out of the box. Tags follow Obsidian's nested format. No required plugins (Dataview, Templater, Canvas). What Obsidian gives for free is used; what it adds via plugins is not depended on.++**Isolation from legacy areas.** No Brain operation writes to `AI Wiki/` or `Daily/`. No legacy operation writes to `Brain/`. The two systems coexist; one is the future, the other is read-only legacy.++**Idempotency of state-changing batch operations.** Running `dream` twice in a row without new input or expired timestamps is a no-op, including in the log. This makes scheduling safe (cron every hour produces noise-free output).++## 4. Vault Layout++```text+<vault>/+βββ AI Wiki/ (legacy, read-only for agents)+βββ Daily/ (legacy event-log + human narrative)+βββ Brain/ (new in v0.9)+ βββ _brain.yaml schema + configuration+ βββ _BRAIN.md operating manual rendered for agents+ βββ inbox/+ β βββ sig-2026-05-14-no-internal-abbrev.md+ β βββ processed/+ β βββ sig-2026-05-13-no-internal-abbrev.md+ βββ preferences/+ β βββ pref-no-internal-abbrev.md+ βββ retired/+ β βββ ret-prefer-bullets-over-prose.md+ βββ log/+ β βββ 2026-05-14.md+ βββ .snapshots/+ βββ dream-2026-05-14-104200.tar.zst+```++The directory a file lives in encodes its current lifecycle state. The frontmatter `status` field duplicates this for convenience. `o2b brain doctor` reports any mismatch.++`inbox/processed/` is a holding area for signals that have already contributed to a preference (or have been folded into an existing one). Files there remain valid wikilink targets β Obsidian resolves by basename regardless of folder.++## 5. File Formats++### 5.1 Common conventions++- Filename: `<prefix>-<slug>.md`, where prefix is `sig`, `pref`, or `ret`. The slug is chosen at creation and never edited.+- All Brain notes have frontmatter fields: `kind`, `id`, `created_at` (ISO-8601 UTC), `tags`.+- `id` equals the filename basename (without `.md`). It is duplicated in frontmatter so it survives manual `mv` operations.+- All cross-references are Obsidian wikilinks, `[[basename]]` or `[[basename|alias]]`. No relative paths.+- `tags` always include `brain` plus a kind-specific path: `brain/signal`, `brain/preference`, `brain/retired`, `brain/log`. Optional `brain/topic/<slug>` and `brain/scope/<scope>` tags improve Obsidian tag pane navigation.++### 5.2 Signal (`sig-...`)++A raw taste signal. Immutable after creation.++Location: `Brain/inbox/sig-<date>-<slug>.md` (or `Brain/inbox/processed/...` after dreaming).++```yaml+---+kind: brain-signal+id: sig-2026-05-14-no-internal-abbrev+created_at: 2026-05-14T10:15:00Z+tags: [brain, brain/signal, brain/topic/no-internal-abbrev, brain/scope/writing]+topic: no-internal-abbrev # required, dedup anchor for dream+scope: writing # optional, soft category+signal: negative # required: positive | negative+agent: claude # required: source agent or human name+source: # optional list of wikilinks to context artifacts+ - "[[Daily/2026.05.14]]"+ - "[[blog-header-draft]]"+principle: Do not use internal abbreviations in user-facing copy unless explained first+---++## Raw++Sergey pointed out that "OSB" appeared as an abbreviation in the blog header+without prior explanation. Agreed it should be spelled out on first use.+```++Required: `kind`, `id`, `created_at`, `tags`, `topic`, `signal`, `agent`, `principle`. Optional: `scope`, `source`. Missing any required field is a write-time error.++`principle` is a one-line, agent-readable formulation of the rule that should emerge if this signal joins others. It is what later becomes the `principle` of a preference.++### 5.3 Preference (`pref-...`)++A rule. Two states: `unconfirmed` (just promoted from signals, not yet applied) and `confirmed` (applied at least once in real work).++Location: `Brain/preferences/pref-<slug>.md`.++```yaml+---+kind: brain-preference+id: pref-no-internal-abbrev+created_at: 2026-05-14T10:42:00Z+confirmed_at: # null until first applied evidence+unconfirmed_until: 2026-05-28T10:42:00Z # window expires; pref retires if no applied evidence by this time+tags: [brain, brain/preference, brain/topic/no-internal-abbrev, brain/scope/writing]+topic: no-internal-abbrev+scope: writing+status: unconfirmed # unconfirmed | confirmed+principle: Do not use internal abbreviations in user-facing copy unless explained first+evidenced_by: # origin signals; fixed at creation+ - "[[sig-2026-05-13-no-internal-abbrev]]"+ - "[[sig-2026-05-14-no-internal-abbrev]]"+ - "[[sig-2026-05-14-spelled-out-osb]]"+applied_count: 0 # computed from log/+violated_count: 0 # computed from log/+last_evidence_at: 2026-05-14T10:42:00Z # computed from log/+confidence: low # computed: low | medium | high+pinned: false # if true, exempt from automatic retire+supersedes: # optional wikilink to retired pref+aliases: [no-internal-abbrev rule]+---++## Principle++Do not use internal abbreviations in user-facing copy unless explained first.++## How to apply++When writing public-facing copy (blog posts, README, marketing pages, public+documentation), expand acronyms on first use. Internal docs and code comments+are exempt.+```++`evidenced_by` is fixed at promotion time and does not grow. Ongoing applications are tracked in `Brain/log/` and aggregated into `applied_count` / `violated_count` during `dream`. Obsidian backlinks from log entries surface them in the preference's backlink pane.++If `pinned: true`, the preference is exempt from the three automatic retire reasons (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`). Only an explicit `o2b brain reject` can retire it. Pinning does not affect evidence accumulation, confidence updates, or rebuttal counters β only the final retire decision. Pinning is set and cleared by CLI-only verbs (`o2b brain pin` / `o2b brain unpin`); autonomous agents cannot change the protected set through MCP.++### 5.4 Retired (`ret-...`)++A preference that left the active loop. Same `id` (renaming keeps the slug but flips the prefix). Lives in `Brain/retired/`.++```yaml+---+kind: brain-retired+id: ret-no-internal-abbrev+status: retired+retired_at: 2026-08-12T05:00:00Z+retired_reason: stale-no-evidence # stale-no-evidence | expired-unconfirmed | rebutted | user-rejected+retired_by: "[[Brain/log/2026-08-12]]" # the dream run that retired it+superseded_by: # optional wikilink to newer preference+# remaining fields inherited from preference (topic, principle, evidenced_by, etc.)+---+```++Retired entries are never deleted. They are the audit trail of what the system once believed.++### 5.5 Log entry++One file per UTC day. Append-only. Events written by every state-changing Brain operation.++Location: `Brain/log/<YYYY-MM-DD>.md`.++```yaml+---+kind: brain-log+date: 2026-05-14+tags: [brain, brain/log]+---++# Brain log β 2026-05-14++## 10:42:00Z β dream+- run_id: dream-2026-05-14-104200+- input_signals: 7+- new_unconfirmed: 1+ - [[pref-no-internal-abbrev]] (topic: no-internal-abbrev, signal_balance: -3)+- confirmed: 0+- retired: 0+- moved_to_processed: 5++## 14:22:00Z β apply-evidence+- preference: [[pref-no-internal-abbrev]]+- artifact: "[[Daily/2026.05.14#section-blog-post]]"+- agent: claude+- result: applied+- note: Expanded "OSB" to "Open Second Brain" on first use.++## 14:55:00Z β apply-evidence+- preference: [[pref-no-internal-abbrev]]+- artifact: "[[Daily/2026.05.14#section-readme-update]]"+- agent: codex+- result: violated+- note: README diff contained unexplained "FT" abbreviation.+```++Each entry is a level-2 heading with `<UTC time> β <event type>` and a bullet list of key/value lines. The event types are: `dream`, `feedback`, `apply-evidence`, `force-confirmed`, `reject`, `promote`, `retire`. Log files are themselves never edited; new events append.++## 6. State Machine++```text+inbox(sig)+ βββ dream, threshold reached ββββΆ preferences/ status: unconfirmed+ β+ βββ first apply-evidence (applied) βββΆ status: confirmed+ β+ βββ rebuttal signals reach threshold ββΆ retired/ reason: rebutted+ β+ βββ no evidence within trial window βββΆ retired/ reason: expired-unconfirmed++ preferences/ status: confirmed+ β+ βββ apply-evidence applied >> violated, fresh evidence βββΆ confidence climbs+ β+ βββ stale_evidence_days passes ββββββββββββββββββββββββββββΆ retired/ reason: stale-no-evidence+ β+ βββ rebuttal signals reach threshold βββββββββββββββββββββββΆ retired/ reason: rebutted++ preferences/ * ββ o2b brain reject ββββββββββββββββββββββββββββββββββββββββββΆ retired/ reason: user-rejected+```++The transitions are driven entirely by `dream` plus `apply-evidence` log entries. No manual approval step exists in the default flow.++## 7. dream Algorithm++`dream` is the only mutating batch operation. It reads the current Brain state and decides which transitions to apply. It is deterministic given the inputs and the configured time.++### 7.1 Inputs++- `Brain/inbox/sig-*.md` (active)+- `Brain/inbox/processed/sig-*.md` (historical, contributes to signal counts where referenced)+- `Brain/preferences/pref-*.md`+- `Brain/retired/ret-*.md` (for supersede checks)+- `Brain/log/*.md` (for `applied`/`violated`/`last_evidence_at`)+- `Brain/_brain.yaml`+- Current time (parameter `--now`, defaults to system time)++### 7.2 Outputs++- New or updated files in `preferences/`+- Moves into `retired/`+- Moves from `inbox/` into `inbox/processed/`+- One appended event in `Brain/log/<today>.md` summarising the run, but only if any state actually changed++### 7.3 Pseudocode++```text+dream(now):+ cfg = load(_brain.yaml)+ active_signals = scan(inbox/, not processed/)+ processed = scan(inbox/processed/)+ preferences = scan(preferences/)+ retired = scan(retired/)+ log_entries = scan(log/)++ # 1. Group all signals by topic+ by_topic = group_by(active_signals + processed, key='topic')++ # 2. Per-topic processing+ for topic, sigs in by_topic:+ pref = find_preference(topic)++ if pref and pref.status in (unconfirmed, confirmed):+ handle_signals_on_active_pref(pref, sigs_active(topic), now, cfg)+ continue++ # No active preference for this topic β consider promotion+ if dominant_sign_count(sigs_active(topic), cfg.contradiction_window_days) >= cfg.candidate_threshold:+ create_unconfirmed_preference(topic, sigs, cfg, now)++ # 3. Refresh active preferences from log/+ for pref in scan(preferences/):+ applied, violated, last_evidence = count_evidence_from_log(pref.id, log_entries)+ pref.applied_count = applied+ pref.violated_count = violated+ pref.last_evidence_at = last_evidence+ pref.confidence = compute_confidence(pref, cfg, now)+ # Status promotion: first applied evidence flips unconfirmed -> confirmed+ if pref.status == unconfirmed and applied >= 1:+ pref.status = confirmed+ pref.confirmed_at = first_applied_at(pref.id, log_entries)+ write_atomic(pref)++ # 4. Retire stale or expired+ for pref in scan(preferences/):+ if pref.status == unconfirmed and now > pref.unconfirmed_until:+ move_to_retired(pref, reason='expired-unconfirmed', now)+ continue+ if pref.status == confirmed and days_between(pref.last_evidence_at, now) > cfg.stale_evidence_days:+ move_to_retired(pref, reason='stale-no-evidence', now)++ # 5. Move consumed signals out of inbox+ for sig in active_signals:+ if is_referenced_by_pref_or_retired(sig):+ move(sig.path, inbox/processed/sig-...)++ # 6. Append a log entry only if anything changed+ if changes:+ append_log_entry(now, run_id, summary)+```++### 7.4 Rules++**Threshold by dominant sign.** `candidate_threshold` requires that many signals of the **same** sign for one topic. Mixed signals do not sum; they cancel within `contradiction_window_days`. Three negatives and one positive within the window equal signal balance -2, below the threshold.++**One preference per topic.** A topic with an existing active preference (unconfirmed or confirmed) never spawns a second one. New signals on the same topic with the same sign refresh evidence; opposite-sign signals start accumulating toward a rebuttal.++**Rebuttal threshold.** Signals contradicting an active preference are counted separately. When their count of the dominant opposite sign reaches `candidate_threshold`, the active preference moves to `retired/` with reason `rebutted`. A fresh `unconfirmed` preference for the new direction is created from the rebuttal signals.++**Unconfirmed-to-confirmed promotion.** The first `apply-evidence` entry with `result: applied` for an `unconfirmed` preference flips its status to `confirmed` and stamps `confirmed_at` with the timestamp of that log entry.++**Confidence formula.**++```text+applied = count(log entries with kind=apply-evidence, result=applied, pref=X)+violated = count(log entries with kind=apply-evidence, result=violated, pref=X)+fresh = (now - pref.last_evidence_at) < cfg.stale_evidence_days * cfg.high_freshness_factor++if applied <= cfg.low_max_applied or (applied > 0 and violated >= applied):+ confidence = low+elif applied >= cfg.high_min_applied and violated == 0 and fresh:+ confidence = high+else:+ confidence = medium+```++**Retirement reasons** are mutually exclusive:+- `stale-no-evidence`: confirmed preference with `last_evidence_at` older than `stale_evidence_days`.+- `expired-unconfirmed`: unconfirmed preference whose `unconfirmed_until` passed without any `applied` evidence.+- `rebutted`: rebuttal signals reached threshold.+- `user-rejected`: explicit `o2b brain reject` command.++**No semantic merging.** Two topics with different slugs (`no-internal-abbrev` and `avoid-abbreviations`) are different counters. Merging is a human decision or an external agent's call, performed by manually editing frontmatter or by submitting new signals with the canonical topic and a `supersedes:` field on the resulting preference. The dream algorithm never guesses.++**Same-sign signals on an active preference.** When a signal arrives on a topic that already has an active preference (unconfirmed or confirmed) and the signal's sign matches the preference, the signal is noted by `dream` (moved to `processed/` with a log entry of type `noted-redundant`) but does not generate a new preference and does not increment `applied_count`. The latter is reserved for `apply-evidence` log entries from real work. Same-sign signals are user reiteration; their value is the reassurance that the topic is still relevant, not a counted application.++**Corrupted frontmatter.** A signal, preference, or retired file whose YAML cannot be parsed is skipped with a warning entry in the run log (`event: skip-corrupted-frontmatter`, `path: <relative path>`). The remaining files are processed normally. Corruption never aborts a run; `o2b brain doctor` is the right tool to surface and resolve it.++**Pre-run snapshot.** Before any state-changing operation in a `dream` run, the algorithm writes `Brain/.snapshots/<run_id>.tar.zst` containing the entire `Brain/` tree (excluding `.snapshots/` itself). Retention: the `snapshots.retention_count` newest files (default 10); older snapshots are pruned at the end of the run. Snapshots are local-only and small (typical compressed size well under 1 MB). They exist solely to enable `o2b brain rollback <run_id>`. If the snapshot itself fails to write, the run aborts before any other change β the safety net cannot be bypassed silently.++**Pin protection.** A preference with `pinned: true` in its frontmatter is exempt from the three automatic retire reasons (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`). The only path to retire a pinned preference is explicit `o2b brain reject --id`, which prints a warning before proceeding. Pinning does not affect evidence accumulation, confidence computation, or rebuttal-counter accumulation β only the final retire decision is suppressed. Pinning and unpinning are CLI-only operations; the MCP surface intentionally does not expose them, so autonomous agents cannot alter the protected set.++**Atomicity per file, not per run.** Each write uses `fs-atomic` (write to temp file in the same directory, then rename). If `dream` crashes mid-run, the filesystem reflects the operations that completed; rerunning dream converges (idempotency guarantees no duplicates).++## 8. Digest Format++Read-only output, sourced from current state and recent log entries. Default window: last 24 hours.++Five sections, each appearing only when non-empty:++1. New (unconfirmed, in trial)+2. Confirmed during the window+3. Retired during the window+4. Confidence shifts during the window+5. Contradictions detected during the window++If all five are empty, the digest collapses to a single line: `Brain digest β <date>: no changes`. With `--silent-if-empty` it produces no output.++### 8.1 Markdown++```markdown+# Brain digest β 2026-05-14T20:00Z (24h)++## New (unconfirmed, in trial)++- [[pref-no-internal-abbrev]] β writing, 3 signals, trial ends 2026-05-28+- [[pref-imperative-prompts]] β coding, 4 signals, trial ends 2026-05-28++## Confirmed++- [[pref-prefer-typed-errors]] β coding, first applied in [[Daily/2026.05.14]]++## Retired++- [[ret-prefer-bullets-over-prose]] β writing, stale-no-evidence (91 days)+- [[ret-old-comment-style]] β coding, rebutted (3 negative signals)++## Confidence shifts++- [[pref-no-internal-abbrev]] medium β high (applied: 11, violated: 0)+```++### 8.2 JSON++```json+{+ "schema_version": 1,+ "generated_at": "2026-05-14T20:00:00Z",+ "window": {+ "since": "2026-05-13T20:00:00Z",+ "until": "2026-05-14T20:00:00Z"+ },+ "summary": {+ "new_unconfirmed_count": 2,+ "confirmed_count": 1,+ "retired_count": 2,+ "confidence_shift_count": 1,+ "contradiction_count": 0,+ "empty": false+ },+ "new_unconfirmed": [+ {+ "id": "pref-no-internal-abbrev",+ "topic": "no-internal-abbrev",+ "scope": "writing",+ "signal_count": 3,+ "signal_balance": -3,+ "unconfirmed_until": "2026-05-28T10:42:00Z",+ "path": "Brain/preferences/pref-no-internal-abbrev.md"+ }+ ],+ "confirmed": [+ {+ "id": "pref-prefer-typed-errors",+ "confirmed_at": "2026-05-14T11:00:00Z",+ "first_applied_artifact": "[[Daily/2026.05.14]]"+ }+ ],+ "retired": [+ {+ "id": "ret-prefer-bullets-over-prose",+ "retired_at": "2026-05-14T05:00:00Z",+ "reason": "stale-no-evidence",+ "days_stale": 91+ }+ ],+ "confidence_shifts": [+ {+ "id": "pref-no-internal-abbrev",+ "from": "medium",+ "to": "high",+ "applied_count": 11,+ "violated_count": 0+ }+ ],+ "contradictions": []+}+```++Exit codes: `0` normal, `1` error, `2` empty and `--silent-if-empty` is set.++## 9. CLI and MCP API++### 9.1 Summary++| Command | Writes | MCP | Idempotent | Read-only |+|---|---|---|---|---|+| `o2b brain init` | Brain/ skeleton | no | yes | no |+| `o2b brain feedback` | inbox/sig-* | yes | no | no |+| `o2b brain dream` | preferences/, retired/, log/, inbox/processed/, .snapshots/ | yes | yes (no-op on rerun) | no |+| `o2b brain apply-evidence` | log/<day>.md (append) | yes | no | no |+| `o2b brain digest` | β | yes | yes | yes |+| `o2b brain query` | β | yes | yes | yes |+| `o2b brain reject` | retired/, log/ | no | no | no |+| `o2b brain pin` | preferences/<id>.md (frontmatter) | no | yes (no-op if already pinned) | no |+| `o2b brain unpin` | preferences/<id>.md (frontmatter) | no | yes (no-op if not pinned) | no |+| `o2b brain rollback` | Brain/ overwritten from snapshot | no | no | no |+| `o2b brain doctor` | β | yes | yes | yes |++`brain init`, `brain reject`, `brain pin`, `brain unpin`, and `brain rollback` are intentionally CLI-only. `init` is a one-time setup; `reject` is a destructive admin action; `pin`/`unpin` change the protected set; `rollback` overwrites the entire `Brain/` tree. Their absence from MCP protects against autonomous mistakes.++### 9.2 Argument and behaviour reference++`o2b brain init [--vault <path>] [--force]`+- Creates `Brain/` skeleton. Requires that machine-local config (`~/.config/open-second-brain/config.yaml`) exists; without it, exits with a message pointing to `o2b init`.+- Without `--force`, refuses if `_brain.yaml` already exists.+- Idempotent without `--force`: re-running is a no-op.++`o2b brain feedback --topic <slug> --signal positive|negative --principle "<text>" [--scope <slug>] [--source "<wikilink>"]+ [--agent <name>] [--raw <text>|--raw-file <path>] [--force-confirmed] [--vault <path>]`+- Creates one `sig-*` in `Brain/inbox/`. With `--force-confirmed`, creates a `pref-*` directly with `status: confirmed`.+- Collisions on slug are resolved by appending `-2`, `-3`, β¦.+- MCP form: `brain_feedback({topic, signal, principle, scope?, source?, agent?, raw?, force_confirmed?}) -> {path, id}`.++`o2b brain dream [--vault <path>] [--dry-run] [--now <ISO-8601>] [--json]`+- Runs the algorithm in section 7. `--dry-run` prints what would happen without writing.+- Idempotent. Returns `0` on success including no-op runs.+- MCP form: `brain_dream({dry_run?, now?}) -> {run_id, new_unconfirmed, confirmed, retired, contradictions, moved_to_processed}`.++`o2b brain apply-evidence --pref <pref-id> --artifact "<wikilink>" --result applied|violated [--agent <name>] [--note "<text>"] [--vault <path>]`+- Appends a single event to `Brain/log/<today>.md`. Does not modify the preference file directly; the next `dream` aggregates.+- If `<pref-id>` does not exist (typo, already retired), exits `2` with an informative message. This is not an error condition.+- MCP form: `brain_apply_evidence({pref_id, artifact, result, agent?, note?}) -> {logged_at, log_path}`.++`o2b brain digest [--vault <path>] [--since <ISO>] [--until <ISO>] [--json] [--silent-if-empty]`+- See section 8.+- MCP form: `brain_digest({since?, until?, format?}) -> {content}`.++`o2b brain query [--vault <path>] [--preference <id>|--topic <slug>|--since <ISO>] [--json]`+- Read helper. Aggregates a preference with its evidence trail, or all artifacts under a topic, or all log events after a timestamp.+- For interactive inspection prefer Obsidian backlinks; this command exists for cron, scripts, and headless agents.+- MCP form: `brain_query({preference?, topic?, since?, format?}) -> {content}`.++`o2b brain reject --id <pref-id> [--reason "<text>"] [--vault <path>]`+- Moves a preference to `Brain/retired/` with reason `user-rejected`. CLI-only. If the preference is `pinned: true`, prints an extra warning and requires `--yes` to proceed.++`o2b brain pin --id <pref-id> [--vault <path>]`+- Sets `pinned: true` in the preference frontmatter; the preference becomes exempt from automatic retire. Idempotent (no-op if already pinned). Logs a `pin` event in `Brain/log/<today>.md`. CLI-only.++`o2b brain unpin --id <pref-id> [--vault <path>]`+- Clears `pinned: true`; the preference becomes subject to automatic retire again. Idempotent. Logs an `unpin` event. CLI-only.++`o2b brain rollback <run_id> [--vault <path>] [--yes]`+- Restores `Brain/` from `Brain/.snapshots/<run_id>.tar.zst`. `<run_id>` appears in `Brain/log/<date>.md` `dream` headers; `o2b brain rollback --list` enumerates available snapshots with their timestamps. Without `--yes` the command prints a diff summary (counts of preferences / retired / signals that will change) and prompts interactively. After restoration, appends a `rollback` event to `Brain/log/<today>.md`. CLI-only; destructive.++`o2b brain doctor [--vault <path>] [--json] [--strict]`+- Checks invariants: status-vs-folder consistency, wikilink resolution, frontmatter validity, ISO parsing, duplicate ids, log header parsing.+- Without `--strict`, warnings exit `0`; with `--strict`, warnings exit `2`. Errors always exit `1`.+- MCP form: `brain_doctor({strict?, format?}) -> {content}`.++### 9.3 General rules for all commands++- No command writes outside `Brain/`. The `path-safety` module enforces this.+- All writers use `fs-atomic` (temp + rename in the same directory).+- All commands resolve vault path from machine-local config when `--vault` is omitted.+- State-changing commands log a single event to `Brain/log/<today>.md` of the corresponding type.+- Environment variable `AGENT_NAME` is honoured by `--agent` defaults; no other env-bound secrets are read.++## 10. Configuration: `Brain/_brain.yaml`++```yaml+schema_version: 1++dream:+ candidate_threshold: 3+ unconfirmed_window_days: 14+ contradiction_window_days: 14++retire:+ stale_evidence_days: 90++confidence:+ low_max_applied: 2+ high_min_applied: 10+ high_freshness_factor: 0.8++snapshots:+ retention_count: 10 # keep this many newest .snapshots/*.tar.zst+```++All values may be edited by hand. `o2b brain doctor` validates ranges and types. Schema version is checked at every read; an unknown version exits `1`.++## 11. Deprecation Policy++OSB prior to Brain ships several agent-facing write paths that overlap conceptually with Brain. The policy is **soft deprecation**: code stays, but agents no longer learn about the legacy paths through the plugin surface.++### 11.1 What becomes invisible to agents++| Surface | Before | After v0.9.0 |+|---|---|---|+| `skills/agent-event-log/SKILL.md` | the agent's main durable-artifact logging skill | moved to `docs/legacy-skills/` and excluded from the loaded skill set |+| `skills/open-second-brain/SKILL.md` | describes writing to `AI Wiki/` and `Daily/` | rewritten to point at Brain; legacy areas mentioned only as read-only |+| MCP tool `event_log_append` | advertised | removed from the exported tools list in `src/mcp/tools.ts`; handler retained |+| MCP tool `second_brain_capture` | advertised | removed from advertised list; handler retained |+| MCP tool `second_brain_query` | advertised | retained (read-only; agents read legacy data through it) |+| Hook `PostToolUse` reminder | "call event_log_append after a durable artifact" | rewritten: signals β `brain_feedback`, applicable preferences β `brain_apply_evidence` |+| Hook `Stop` guardrail | blocked once on missing `event_log_append` | removed in v0.9; no Brain-specific guardrail added in v0.9 |+| Vault file `AI Wiki/_OPEN_SECOND_BRAIN.md` | describes agent-owned AI Wiki rules | overwritten by `o2b brain init` to a Brain-first manual; legacy area listed as read-only |++### 11.2 What remains visible++- Pay Memory: all 11 CLI commands and 8 MCP tools unchanged. Pay Memory is an audit layer for paid actions, orthogonal to the learning loop. A future task can wire payment receipts into Brain (e.g., as a signal scope `paid-action`), but that is out of v0.9 scope.+- Read-only legacy surfaces: `second_brain_query`, `o2b status`, `o2b doctor`, `o2b export-config`, `o2b index`.+- CLI commands for legacy writes (`o2b append-event`, `vault-log`, AI Wiki bootstrap inside `o2b init`) remain callable by a human in a shell; they are not advertised to agents.++### 11.3 Code retention++- `src/core/event-log.ts` writers stay.+- `src/core/init.ts` AI Wiki bootstrap stays.+- `src/mcp/handlers/event_log_append.ts` and `second_brain_capture.ts` stay; only the entries in the exported tools array are removed.+- Old skill files are moved into `docs/legacy-skills/` so the runtime skill scanner does not load them. The Markdown remains accessible as documentation.++Hard removal is deferred to v0.10 or later, gated on observed usage of Brain (no calls to legacy `event_log_append` / `second_brain_capture` MCP tools recorded after v0.9 has accumulated a sustained activity volume in `Brain/log/`).++## 12. Migration and Release++### 12.1 Migration++For an existing vault, the migration is a single command:++```bash+o2b brain init --vault /path/to/vault+```++This creates `Brain/` and overwrites `AI Wiki/_OPEN_SECOND_BRAIN.md` with the Brain-first manual. With approximately zero current users beyond the project owner, no backup of the previous `_OPEN_SECOND_BRAIN.md` is kept; the design source-of-truth for the new file is this document and the implementation's template.++No data migration is performed. Existing `AI Wiki/` notes and `Daily/` entries remain on disk; agents read them via `second_brain_query`.++### 12.2 Plugin manifests++All four runtime manifests (Hermes `plugin.yaml`, Claude `.claude-plugin/plugin.json`, Codex `.codex-plugin/plugin.json`, OpenClaw `openclaw.plugin.json`) receive:++- Version bump to `0.5.0` (synced via `bun run sync-version`).+- Advertised tool list updated: remove `event_log_append` and `second_brain_capture`, add the six Brain MCP tools (Hermes, Claude, Codex; OpenClaw's native JS implementation is deferred to v0.9.1 and its `contracts.tools[]` keeps the legacy set until then).+- New advertised CLI commands `o2b brain init|feedback|dream|apply-evidence|digest|query|reject|doctor` in the manifests that enumerate commands.++### 12.3 CHANGELOG++A single entry under existing version headers, following the project's "no Unreleased section" convention:++```markdown+## 0.9.0 β YYYY-MM-DD++### Added+- Brain: observing memory layer at `Brain/` with deterministic dream.+- CLI namespace `o2b brain *` (11 verbs).+- MCP tool namespace `brain_*` (6 tools).+- Pre-run snapshot of `Brain/` to `.snapshots/<run_id>.tar.zst` before each `dream`; `o2b brain rollback <run_id>` restores. Retention configurable in `_brain.yaml`.+- Pin protection: preferences marked `pinned: true` skip automatic retire (stale, expired, rebutted). CLI verbs `o2b brain pin` / `o2b brain unpin`.+- Skill `brain-memory` instructing agents when to record signals and apply evidence.+- Digest output (Markdown + JSON) for terminal and Hermes cron delivery.++### Changed+- `_OPEN_SECOND_BRAIN.md` rewritten by `o2b brain init` to point agents at Brain.+- `PostToolUse` and `Stop` hooks reminders re-targeted to Brain.+- `Stop` guardrail removed in v0.9; no Brain-specific guardrail added.++### Deprecated (agent-facing only, code retained)+- MCP tool `event_log_append` β agents are guided to `brain_feedback` and `brain_apply_evidence`. CLI `o2b append-event` and `vault-log` remain callable for humans.+- MCP tool `second_brain_capture` β agents write to `Brain/` only.+- Skill `agent-event-log` moved to `docs/legacy-skills/`.++### Notes+- Pay Memory unchanged; remains agent-visible.+- `AI Wiki/` remains on disk; agents read via `second_brain_query`, do not write.+- OpenClaw native parity for Brain deferred to v0.9.1.+```++### 12.4 GitHub release++Title: `v0.9.0 β Observing memory layer (Brain)`. Body: the CHANGELOG entry above, with the conceptual framing from section 1 condensed.++## 13. Testing Strategy++Tests target invariants of the loop and the fact of deprecation, not coverage percentages.++### 13.1 Unit++- Frontmatter parsing for every kind; required fields raise specific errors.+- Slug collision: a second `brain feedback` with the same slug receives `-2`.+- Confidence formula at boundary cases: `low_max_applied`, `high_min_applied`, `violated >= applied`, freshness boundary.+- Wikilink serialisation and resolution.+- Atomic write failure modes: temp written but rename interrupted leaves vault consistent.+- `_BRAIN.md.tpl` template is under 200 lines (compliance ceiling for agent-facing operating manuals).+- Snapshot rotation: after `snapshots.retention_count + N` dream runs, only `retention_count` newest snapshot files remain in `.snapshots/`.++### 13.2 Integration scenarios++- Happy path: 3 signals β `dream` β unconfirmed preference β `apply-evidence applied` β `dream` β confirmed preference with `applied_count: 1`.+- Rebuttal: confirmed preference + 3 opposite-sign signals β retired with `reason: rebutted`.+- Expired-unconfirmed: unconfirmed preference + `--now` past `unconfirmed_until` β retired with `reason: expired-unconfirmed`.+- Stale-no-evidence: confirmed preference + `last_evidence_at` past `stale_evidence_days` β retired with `reason: stale-no-evidence`.+- Contradiction window: 2 negative + 1 positive within `contradiction_window_days` β no unconfirmed preference created.+- `--force-confirmed`: bypasses inbox; preference created with `status: confirmed`.+- `brain reject`: preference moved to retired with `reason: user-rejected`.+- Pin protection: confirmed preference with `pinned: true`, clock past `stale_evidence_days` β `dream` does NOT retire; preference stays in `preferences/`. Same assertion for `expired-unconfirmed` and `rebutted` paths.+- Rollback: take vault snapshot A; run `brain feedback` + `brain dream` producing state B; `o2b brain rollback <run_id> --yes` restores byte-identical state A in `Brain/` (excluding `.snapshots/` retention bookkeeping).++### 13.3 Determinism++- Idempotency: two consecutive `dream` runs without new input or expired timestamps produce no log entry on the second run.+- Replay byte-determinism: with `--now` fixed, two runs on a fresh copy of the same fixture produce byte-identical output.++### 13.4 Schema and configuration++- `_brain.yaml` missing `schema_version` β exit `1`.+- Threshold out of bounds (negative or non-integer) β exit `1`.+- Corrupted YAML in one signal file β skipped with a warning; other signals processed.++### 13.5 Doctor++- Status-vs-folder mismatch reported.+- Broken wikilink in `evidenced_by` reported.+- Duplicate `id` across files β error.+- Invalid ISO in `unconfirmed_until` β error.++### 13.6 Digest++- Empty window with default mode β one-line output.+- Empty window with `--silent-if-empty` β exit `2`, no output.+- Each section renders correctly when its data is present.+- JSON output validates against a checked-in schema.++### 13.7 CLI++- Each `o2b brain *` command: happy path; missing required argument exits `1` naming the field; missing vault config exits `1` with a hint pointing to `o2b init`.++### 13.8 MCP++- Each `brain_*` tool returns the documented structure; descriptors are valid JSON Schema.++### 13.9 Deprecation++- `src/mcp/tools.ts` exported list does not contain `event_log_append` or `second_brain_capture`.+- Plugin manifests (`plugin.yaml`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`) do not advertise the deprecated tools.+- `hooks/hooks.json` PostToolUse prompt does not contain the string `event_log_append`; contains `brain_feedback` or `brain_apply_evidence`.+- `hooks/hooks.json` Stop hook has no blocking logic on `event_log_append`.+- `skills/` does not contain `agent-event-log/`; the file lives in `docs/legacy-skills/`.+- `skills/open-second-brain/SKILL.md` body does not include legacy write instructions for `AI Wiki/notes/`, `event_log_append`, or `vault-log`.++### 13.10 Migration++- `o2b brain init` on an empty vault creates the skeleton; rerun is a no-op.+- `o2b brain init --force` overwrites `_brain.yaml`.+- `o2b brain init` without prior `o2b init` exits `1` with a hint.++### 13.11 End-to-end lifecycle++A single timed scenario, fixture-based, asserting the full loop:++```text+day 1: o2b init && o2b brain init+day 1: brain feedback Γ3 (negative, topic X)+day 1: brain dream β 1 unconfirmed preference+day 2: brain apply-evidence applied+day 2: brain dream β confirmed, applied_count=1+day 3: brain apply-evidence applied Γ9+day 3: brain dream β confidence: high+day 30: brain dream β still in preferences/+day 95: brain dream β retired with reason stale-no-evidence+```++This is the golden snapshot. Any dream regression fails it.++### 13.12 Fixtures++`tests/fixtures/brain/` contains static vault snapshots: `empty/`, `populated-loop/`, `contradicted/`, `stale-pref/`, `corrupted-frontmatter/`. Tests copy to tmp before running.++### 13.13 Out of v0.9 test scope++- Performance and load (expected file count under 1000).+- LLM-driven semantic merging (not implemented).+- OpenClaw native JS path (shipped in v0.9.1 with its own tests).+- Hook enforcement for Brain (no enforcement in v0.9; only reminder text is tested).+- Cross-runtime integration (Hermes scanner, Claude marketplace) β exercised manually post-release.++## 14. File Structure++**New files:**++- `src/core/brain/index.ts` β re-exports of the public Brain API.+- `src/core/brain/types.ts` β shared interfaces for signal, preference, retired, log event, config; status and retire-reason enums.+- `src/core/brain/paths.ts` β `brainDirs(vault)`, `signalPath`, `preferencePath`, `retiredPath`, `logPath`, slug-allocator with collision suffixes.+- `src/core/brain/policy.ts` β `loadBrainConfig`, `validateBrainConfig`, `DEFAULT_BRAIN_CONFIG`, threshold and confidence constants.+- `src/core/brain/signal.ts` β `parseSignal`, `writeSignal`, signal frontmatter contract.+- `src/core/brain/preference.ts` β `parsePreference`, `writePreference`, `moveToRetired`.+- `src/core/brain/log.ts` β `parseLogDay`, `appendLogEvent`, event-type enums.+- `src/core/brain/dream.ts` β the deterministic algorithm in section 7.+- `src/core/brain/apply-evidence.ts` β appends one `apply-evidence` log entry.+- `src/core/brain/digest.ts` β Markdown and JSON renderers.+- `src/core/brain/query.ts` β `queryByPreference`, `queryByTopic`, `queryByLogSince`.+- `src/core/brain/doctor.ts` β invariant checks.+- `src/core/brain/init.ts` β `bootstrapBrain(vault, opts)`.+- `src/core/brain/snapshot.ts` β `createSnapshot(vault, run_id)`, `listSnapshots(vault)`, `pruneSnapshots(vault, retention_count)`, `restoreSnapshot(vault, run_id)`. Pre-run safety net for `dream`.+- `src/core/brain/pin.ts` β `setPinned(vault, pref_id, value)`, `isPinned(pref)`.+- `src/core/brain/templates/_BRAIN.md.tpl` β operating manual rendered into the vault (must stay under 200 lines).+- `src/core/brain/templates/_OPEN_SECOND_BRAIN.md.tpl` β Brain-first replacement for the legacy file.+- `src/cli/brain.ts` β `o2b brain *` subcommand dispatcher.+- `src/mcp/brain-tools.ts` β six `ToolDefinition` entries: `brain_feedback`, `brain_dream`, `brain_apply_evidence`, `brain_digest`, `brain_query`, `brain_doctor`.+- `skills/brain-memory/SKILL.md` β agent instruction for when to call `brain_feedback` and `brain_apply_evidence`.+- `tests/core/brain.types.test.ts`, `brain.policy.test.ts`, `brain.paths.test.ts`, `brain.signal.test.ts`, `brain.preference.test.ts`, `brain.log.test.ts`, `brain.dream.test.ts`, `brain.apply-evidence.test.ts`, `brain.digest.test.ts`, `brain.query.test.ts`, `brain.doctor.test.ts`, `brain.init.test.ts`, `brain.snapshot.test.ts`, `brain.pin.test.ts`.+- `tests/cli/brain.test.ts` β exercises every `o2b brain *` verb via `main(argv)`.+- `tests/mcp/brain.test.ts` β exercises all six tools via `MCPServer.callTool`; asserts deprecated tools absent from advertised list.+- `tests/e2e/brain-lifecycle.test.ts` β 95-day timed scenario from section 13.11.+- `tests/fixtures/brain/empty/`, `populated-loop/`, `contradicted/`, `stale-pref/`, `corrupted-frontmatter/` β static vault snapshots.++**Modified files:**++- `src/cli/main.ts` β register `brain` subcommand and extend `HELP`.+- `src/mcp/tools.ts` β register six Brain tools in `buildToolTable()`; remove `event_log_append` and `second_brain_capture` entries from the exported list (handlers retained on disk but not advertised).+- `src/mcp/instructions.ts` β replace the paragraph that points agents at `event_log_append`/`second_brain_capture` with one describing Brain tools.+- `hooks/hooks.json` β rewrite `PostToolUse` reminder text; remove `Stop` guardrail block gating on missing `event_log_append`.+- `skills/open-second-brain/SKILL.md` β body rewritten to point agents at Brain as the writable layer; legacy `AI Wiki/` mentioned only as read-only.+- `package.json`, `plugin.yaml`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `openclaw.plugin.json` β version bump to `0.5.0`; advertised tools/commands updated. OpenClaw `contracts.tools[]` retains legacy Brain-absent set until v0.9.1.+- `README.md` β new `## Brain (observing memory)` section with CLI usage and a link to this plan.+- `docs/architecture.md` β new "Brain layer" subsection; update the layer diagram.+- `docs/hermes-cron.md` β ready-to-paste `hermes cron create` recipe for daily digest delivery.+- `CHANGELOG.md` β `## 0.9.0 β YYYY-MM-DD` entry per section 12.3.++**Moved files:**++- `skills/agent-event-log/` β `docs/legacy-skills/agent-event-log/` (entire directory move).++---++## 15. Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++### Task 1: Core types, paths, config++**Files:**+- Create: `src/core/brain/index.ts`, `types.ts`, `paths.ts`, `policy.ts`.+- Create: `tests/core/brain.types.test.ts`, `brain.paths.test.ts`, `brain.policy.test.ts`.++Types in `types.ts` include the `pinned: boolean` field on `BrainPreference` (default `false` when parsing notes that lack it). `paths.ts` introduces `snapshotsDir(vault)` and `snapshotPath(vault, run_id)`. `policy.ts` validates the new `snapshots.retention_count` config field (positive integer, default 10).++- [ ] **Step 1: define interfaces in `types.ts` β `BrainSignal`, `BrainPreference`, `BrainRetired`, `BrainLogEvent`, `BrainConfig`; status and retire-reason enums.**+- [ ] **Step 2: implement `paths.ts` with all path helpers and slug-collision allocator; pin behavior with tests.**+- [ ] **Step 3: implement `policy.ts` β `DEFAULT_BRAIN_CONFIG`, YAML loader and validator. Tests cover happy path, missing `schema_version`, out-of-bounds thresholds, `high_freshness_factor` range.**+- [ ] **Step 4: `index.ts` re-exports the public surface.**+- [ ] **Step 5: run `bun test tests/core/brain.{types,paths,policy}.test.ts`.**++### Task 2: Frontmatter parsers and writers++**Files:**+- Create: `src/core/brain/signal.ts`, `preference.ts`, `log.ts`.+- Create: `tests/core/brain.signal.test.ts`, `brain.preference.test.ts`, `brain.log.test.ts`.++- [ ] **Step 6: implement `signal.ts` β `parseSignal`, `writeSignal`. Tests cover required-field validation, roundtrip byte-equality, wikilink preservation, slug collision suffixes.**+- [ ] **Step 7: implement `preference.ts` β `parsePreference`, `writePreference`, `moveToRetired`. Tests cover both `unconfirmed` and `confirmed` states; status-vs-folder invariant on read.**+- [ ] **Step 8: implement `log.ts` β `parseLogDay`, `appendLogEvent` (atomic). Tests cover append-only invariant, multi-event days, malformed-entry tolerance, ISO time parsing.**++### Task 3: dream algorithm and apply-evidence++**Files:**+- Create: `src/core/brain/dream.ts`, `apply-evidence.ts`, `snapshot.ts`, `pin.ts`.+- Create: `tests/core/brain.dream.test.ts`, `brain.apply-evidence.test.ts`, `brain.snapshot.test.ts`, `brain.pin.test.ts`.++- [ ] **Step 9: implement `apply-evidence.ts` β appends one event to `Brain/log/<today>.md`; returns logged_at and log_path; exits informatively when preference absent. Tests cover happy path, missing pref, log file creation on first event of day.**+- [ ] **Step 9a: implement `snapshot.ts` β `createSnapshot`, `listSnapshots`, `pruneSnapshots`, `restoreSnapshot`. Uses `tar` + `zstd` available on the host (or the project's existing archive helper). Tests cover createβrestore byte-equality, rotation per `retention_count`, refusal to include `.snapshots/` itself, and snapshot-write-failure β dream aborts cleanly.**+- [ ] **Step 9b: implement `pin.ts` β `setPinned(vault, pref_id, true|false)` rewrites only the `pinned` frontmatter field via `fs-atomic`; `isPinned(pref)` reads the field with default `false`. Tests cover idempotent set, no body modification, log-event emission.**+- [ ] **Step 10: implement `dream.ts` step group A β group signals by topic, create unconfirmed prefs on dominant-sign threshold. Tests cover threshold edge cases and contradiction window collapse.**+- [ ] **Step 11: extend with step group B β refresh `applied_count`/`violated_count` from log, promote unconfirmedβconfirmed on first `applied` evidence, compute `confidence`. Tests cover the full confidence formula by boundary cases.**+- [ ] **Step 12: extend with step group C β retire `expired-unconfirmed`, `stale-no-evidence`, and `rebutted` paths, each gated by `isPinned(pref)` (pinned preferences are exempt from all three automatic reasons). Tests cover all four retirement reasons (incl. `user-rejected` exercised via `reject` CLI in Task 6) and the pin-skip path for each automatic reason.**+- [ ] **Step 12a: integrate `createSnapshot` as the first state-changing step inside `dream` (after computing the planned changes, before writing any file). Snapshot failure aborts the run with exit 1 and no state changes. After successful run, `pruneSnapshots` enforces retention. Tests assert snapshot presence before any mutation and snapshot absence on a no-op run.**+- [ ] **Step 13: implement signal-move to `processed/` and `noted-redundant` log events for same-sign signals on active prefs; `skip-corrupted-frontmatter` warning entries. Tests cover same-sign-on-active-pref and corrupted YAML tolerance.**+- [ ] **Step 14: determinism test β fixture with frozen `--now` produces byte-identical filesystem output across two runs.**++### Task 4: Read helpers (digest, query, doctor)++**Files:**+- Create: `src/core/brain/digest.ts`, `query.ts`, `doctor.ts`.+- Create: `tests/core/brain.digest.test.ts`, `brain.query.test.ts`, `brain.doctor.test.ts`.++- [ ] **Step 15: implement `digest.ts` β Markdown and JSON renderers per section 8. Tests cover per-section rendering, empty-window collapse, JSON-schema validation of the structured form.**+- [ ] **Step 16: implement `query.ts` β `queryByPreference`, `queryByTopic`, `queryByLogSince`. Tests cover evidence-trail aggregation and topic spans.**+- [ ] **Step 17: implement `doctor.ts` β every invariant from section 13.5 as a discrete check. Tests cover each invariant in isolation plus a full run on the `populated-loop` fixture.**++### Task 5: Init and templates++**Files:**+- Create: `src/core/brain/init.ts`, `templates/_BRAIN.md.tpl`, `templates/_OPEN_SECOND_BRAIN.md.tpl`.+- Create: `tests/core/brain.init.test.ts`.++- [ ] **Step 18: write `_BRAIN.md.tpl` β operating manual covering folder roles, signal/preference lifecycle, escape hatches; reviewed for clarity since this is what agents read every session. Hard constraint: under 200 lines (empirical compliance ceiling for agent-facing manuals). A test asserts the line count.**+- [ ] **Step 19: write `_OPEN_SECOND_BRAIN.md.tpl` β Brain-first replacement; legacy `AI Wiki/` noted as read-only.**+- [ ] **Step 20: implement `bootstrapBrain(vault, opts)` β creates `Brain/{inbox/,inbox/processed/,preferences/,retired/,log/}`, writes `_brain.yaml` from default constant, renders both templates. Idempotent without `--force`; `--force` re-renders templates and resets `_brain.yaml`. Overwrites `AI Wiki/_OPEN_SECOND_BRAIN.md` to Brain-first version.**+- [ ] **Step 21: tests cover empty-vault bootstrap, idempotent rerun, `--force` overwrite, prior-config-missing error case (`o2b init` not run yet).**++### Task 6: CLI dispatcher++**Files:**+- Modify: `src/cli/main.ts`.+- Create: `src/cli/brain.ts`, `tests/cli/brain.test.ts`.++- [ ] **Step 22: scaffold `src/cli/brain.ts` β subcommand parser, shared `--vault` and `--json` flags, dispatch by verb.**+- [ ] **Step 23: implement handlers for `init`, `feedback`, `dream`, `apply-evidence`, `digest`, `query`, `reject`, `doctor`. Each handler returns the exit codes documented in section 9.**+- [ ] **Step 23a: implement `pin` and `unpin` handlers β wrap `setPinned`; idempotent; append `pin`/`unpin` event to `log/<today>.md`. CLI-only, not exposed in MCP.**+- [ ] **Step 23b: implement `rollback` handler β wraps `listSnapshots` (for `--list`) and `restoreSnapshot`. Default interactive: print diff summary of preferences/retired/signal counts and prompt y/N; `--yes` skips prompt. Append `rollback` event to `log/<today>.md` after successful restore. `reject` handler also gains a guard: if target preference has `pinned: true`, require `--yes` and print a warning naming the pin.**+- [ ] **Step 24: wire `brain` into `main.ts` dispatcher; extend `HELP` text.**+- [ ] **Step 25: CLI tests β happy path for each verb (incl. `pin`, `unpin`, `rollback`), missing required argument exits `1` naming the field, missing vault config exits `1` with a hint, full exit-code matrix. Rollback test exercises `--list` and `--yes` paths and asserts the pinned-protection warning in `reject`.**++### Task 7: MCP tools and deprecation cleanup++**Files:**+- Modify: `src/mcp/tools.ts`, `src/mcp/instructions.ts`.+- Create: `src/mcp/brain-tools.ts`, `tests/mcp/brain.test.ts`.+- Modify: `hooks/hooks.json`.+- Move: `skills/agent-event-log/` β `docs/legacy-skills/agent-event-log/`.+- Modify: `skills/open-second-brain/SKILL.md`.+- Create: `skills/brain-memory/SKILL.md`.++- [ ] **Step 26: implement six `ToolDefinition` entries in `brain-tools.ts` mirroring the CLI inputs per section 9.**+- [ ] **Step 27: register Brain tools in `buildToolTable()`; remove `event_log_append` and `second_brain_capture` entries from the exported list. Handlers remain on disk.**+- [ ] **Step 28: rewrite `instructions.ts` β drop the legacy paragraph; add a paragraph describing Brain tools and the record-then-apply loop.**+- [ ] **Step 29: MCP tests β e2e exercise of six Brain tools; assertion that `event_log_append` and `second_brain_capture` are not in the advertised list.**+- [ ] **Step 30: rewrite `PostToolUse` hook reminder text per section 11.1; remove `Stop` guardrail block. Hook tests assert the new text and the removed block.**+- [ ] **Step 31: move `skills/agent-event-log/` directory to `docs/legacy-skills/agent-event-log/`. Rewrite `skills/open-second-brain/SKILL.md` body. Create `skills/brain-memory/SKILL.md` instructing agents per the loop in section 6.**++### Task 8: Manifests, docs, release, and PR++**Files:**+- Modify: `package.json`, `plugin.yaml`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `openclaw.plugin.json`, `README.md`, `docs/architecture.md`, `docs/hermes-cron.md`, `CHANGELOG.md`.++- [ ] **Step 32: README β add `## Brain (observing memory)` section with CLI usage block and the principle from section 1; cross-link to this plan.**+- [ ] **Step 33: `docs/architecture.md` β add Brain layer subsection and update the layer diagram.**+- [ ] **Step 34: `docs/hermes-cron.md` β append the `hermes cron create` recipe for daily digest delivery.**+- [ ] **Step 35: `CHANGELOG.md` β add `## 0.5.0 - 2026-MM-DD` per section 12.3 (no `Unreleased` section).**+- [ ] **Step 36: version bump to `0.5.0`; `bun run sync-version` propagates to all manifests. OpenClaw `contracts.tools[]` keeps the legacy set until v0.9.1.**+- [ ] **Step 37: run `bun run typecheck && bun test` end-to-end. All tests including `brain-lifecycle` e2e must be green.**+- [ ] **Step 38: branch `feature/v0.9.0-brain`; commit; push; open PR `feat: brain observing memory layer (v0.9.0)`.**++---++## 16. Post-v0.9 Roadmap++Future work for Brain is tracked in a dedicated, trigger-based document:++- **File:** `docs/plans/2026-05-15-brain-roadmap.md`+- **ID scheme:** `BRAIN-FUT-NNN` (immutable across the lifetime of an item).+- **Indexing:** items are grouped by category (Engine, Capture, Surface, Integration, Lifecycle).+- **Prioritisation rule:** each item has an explicit **trigger condition** based on observed data in the running Brain (`Brain/log/`, `preferences/`, β¦) or on dependencies between items. No calendar-based scheduling.+- **Lifecycle:** items move out of the roadmap into their own design doc (`docs/plans/<topic>.md`) when work begins. Removed items keep their ID retired (not reused).++Permanently out of scope (recorded here for posterity; not in the roadmap): on-chain anchoring of Brain hashes (Solana memo, web3 RPC). Brain's audit trail is the vault itself; this aligns with the OSB-wide policy noted in the Pay Memory plan.++## 17. References++- *Improvement* note in Sergey's vault: `Projects/OpenSecondBrain/Plan/2. Improvement`. Source of the nine extension proposals folded into this design.+- Forbes, *Claude's New Dreaming Feature Builds Self-Improving AI Agents*, Jon Markman, 2026-05-11. Conceptual anchor: asynchronous dreaming pass over an agent's memory store, with a separate staging layer reviewable by humans before deployment.+- Existing OSB design documents: `docs/idea.md`, `docs/architecture.md`, `docs/roadmap.md`. Brain extends but does not replace these.+- Existing OSB plan documents: `docs/plans/2026-05-06-cli-foundation.md`, `docs/plans/2026-05-10-pay-memory.md`. This document follows the same plans-folder convention.diff --git a/docs/plans/2026-05-15-brain-roadmap.md b/docs/plans/2026-05-15-brain-roadmap.mdnew file mode 100644index 00000000..aabac248--- /dev/null+++ b/docs/plans/2026-05-15-brain-roadmap.md@@ -0,0 +1,207 @@+# Brain Post-v0.9 Roadmap++Status: living document+Target: items deferred from v0.9.0 (see `2026-05-15-brain-observing-memory.md`)++## Purpose++This document tracks Brain features that were deferred beyond the v0.9.0 release. It is the canonical place to look when asking "what's next for Brain?" and the canonical place to add an item that doesn't fit in the v0.9 scope.++The document is **trigger-based**, not schedule-based. Each item has an explicit data-driven or dependency-driven condition under which it should be pulled forward into a real plan. Items do not have calendar deadlines.++## Authoring rules++- **IDs are immutable.** `BRAIN-FUT-001` is `001` forever. If an item is removed, retired, or superseded, its ID is not reused. Cross-references (commits, PRs, other docs) keep working.+- **Triggers are observable.** A trigger must be checkable by reading `Brain/log/`, `Brain/preferences/`, runtime telemetry, or an explicit user/agent request. "Feels stable" does not qualify.+- **No calendar dates.** Phrases like "in Q3", "after 2 weeks", "by end of month" are forbidden. Dependencies on releases (`after v0.9.1 ships`) and on data conditions (`after β₯50 apply-evidence entries accumulate`) are the only valid time references.+- **One item, one motivation.** Each item answers a specific observed or anticipated need; if the need isn't articulated, the item doesn't belong here.+- **Move out, don't grow in place.** When work on an item begins, create a separate `docs/plans/<topic>.md` design doc (following the v0.9 plan structure) and delete the entry here. The ID stays referenced by the new plan's title or frontmatter.++## Index++| ID | Title | Category |+|---|---|---|+| [BRAIN-FUT-001](#brain-fut-001--workflow-auto-detection) | Workflow auto-detection | Engine |+| [BRAIN-FUT-002](#brain-fut-002--cross-topic-contradiction-detection) | Cross-topic contradiction detection | Engine |+| [BRAIN-FUT-003](#brain-fut-003--soft-stop-hook-reminder-for-brain_feedback) | Soft Stop-hook reminder for `brain_feedback` | Capture |+| [BRAIN-FUT-004](#brain-fut-004--external-research-as-signal-source) | External research as signal source | Capture |+| [BRAIN-FUT-005](#brain-fut-005--portable-subgraph-export) | Portable subgraph export | Surface |+| [BRAIN-FUT-006](#brain-fut-006--active-preference-injection-via-per-turn-hook) | Active-preference injection via per-turn hook | Surface |+| [BRAIN-FUT-007](#brain-fut-007--openclaw-native-js-parity-for-brain-tools) | OpenClaw native JS parity for Brain tools | Integration |+| [BRAIN-FUT-008](#brain-fut-008--pay-memory--brain-bridge) | Pay Memory β Brain bridge | Integration |+| [BRAIN-FUT-009](#brain-fut-009--hard-removal-of-deprecated-legacy-write-paths) | Hard removal of deprecated legacy write paths | Lifecycle |+| [BRAIN-FUT-010](#brain-fut-010--high-confidence-preference-codification-into-brain-memory-skill) | High-confidence preference codification into `brain-memory` skill | Lifecycle |++## Engine++### BRAIN-FUT-001 β Workflow auto-detection++**Trigger to pull forward:**+- `Brain/log/` contains β₯50 `apply-evidence` entries spread across β₯30 distinct artifacts, AND+- A manual or scripted scan reveals at least 3 recognisable repeated sub-sequences of length β₯3 in the log, AND+- A user or another agent has asked at least once, in a recorded interaction, "can you save this as a routine / workflow?"++**Dependencies:** v0.9 in productive use long enough to satisfy the data conditions above. No code dependencies on other roadmap items.++**Scope sketch:**+- New module `src/core/brain/workflow.ts` β deterministic sequence detector (no embeddings, no LLM).+- New directory `Brain/workflows/` with a documented frontmatter schema.+- `dream` algorithm gains a step-group: detect, cluster by structural similarity, emit candidate workflow notes analogous to unconfirmed preferences.+- CLI verbs `o2b brain workflows list / suggest / approve <id>`.++**Why deferred:** the clustering thresholds and sequence-similarity metric cannot be designed sensibly without real `Brain/log/` data. Picking thresholds on hypothetical traces produces algorithms that fire on noise or never fire at all.++### BRAIN-FUT-002 β Cross-topic contradiction detection++**Trigger to pull forward:**+- At least 2 user-reported cases where two confirmed preferences in different topics produced operationally contradictory guidance, AND+- The same-topic rebuttal logic shipped in v0.9 has been observed to produce a low false-positive rate (no spurious retires under normal use).++**Dependencies:** v0.9 same-topic rebuttal flow stable; ideally also BRAIN-FUT-006 (active-preference injection), because contradictions are easier to surface when the agent is actively applying preferences.++**Scope sketch:**+- Augment `o2b brain doctor` (and `dream`) with a check that compares pairs of confirmed preferences using a deterministic rule set: shared `applies_to` scope plus opposite-direction principle markers.+- Surface candidate contradictions in `digest` under a new section.+- No automatic retire action; flag only. Resolution is a human or agent decision.++**Why deferred:** the rule set requires real examples of cross-topic contradictions to be useful. Designing rules on hypotheticals produces brittle heuristics.++## Capture++### BRAIN-FUT-003 β Soft Stop-hook reminder for `brain_feedback`++**Trigger to pull forward:**+- Multi-session observation that agents systematically miss preference signals in conversation (the user said "don't do X" but no `brain_feedback` was recorded), AND+- The miss rate is high enough that the cost of a soft reminder is justified by the catch rate.++**Dependencies:** v0.9 ships; `brain-memory` skill loaded across runtimes; `Brain/log/` has enough sessions to estimate the miss rate.++**Scope sketch:**+- Extend `hooks/hooks.json` Stop hook with a heuristic: if the latest turn contains preference-marker phrases (negations, explicit corrections, "use X instead", "stop doing Y") AND no `brain_feedback` MCP call happened in the turn, emit a soft reminder. Never blocks the Stop.++**Why deferred:** the phrases that mark preferences cleanly are not knowable in advance. Without observation, the heuristic is either too aggressive (false positives, agent annoyance) or too conservative (no real catch). Wait for real misses, then tune.++### BRAIN-FUT-004 β External research as signal source++**Trigger to pull forward:**+- User actively wants community/shared preferences from external sources (research papers, blog posts, agent-best-practices digests), AND+- A specific incoming source is identified (a URL feed, a curated bundle, a peer's exported subgraph).++**Dependencies:** BRAIN-FUT-005 (portable subgraph export and import format). Without it, no external signals can land in Brain with proper attribution.++**Scope sketch:**+- New `source_type: external` on signals.+- Trust-tier model: external signals do not contribute to the `candidate_threshold` count by themselves; they must be co-signed by at least one local signal of the same direction before promotion.+- Source pinning: each external signal references its origin URL/document with a checksum.++**Why deferred:** no real demand. v0.9 produces only local preferences. External-source ingestion is meaningful once a portable format exists and a use case has materialised.++## Surface++### BRAIN-FUT-005 β Portable subgraph export++**Trigger to pull forward:** an actual import target exists β a second vault to merge into, a team-shared bundle to broadcast, or an external system that consumes preferences.++**Dependencies:** v0.9 stable.++**Scope sketch:**+- `o2b brain export-profile` extracts a self-contained Markdown tree of `preferences/` (filtered: `status: confirmed`, optionally `pinned: true` only) plus their origin `evidenced_by` signals and any `supersedes` / `applies_to` edges.+- Output format: wikilinks rewritten to be relative within the bundle; frontmatter `id` preserved.+- Companion `o2b brain import-profile <bundle>` validates the schema, merges into the local Brain, and produces a conflict report.++**Why deferred:** without a real import target, the export "lands in the void" and we cannot validate the schema against actual use. Premature design of a cross-vault format produces something that won't fit real consumers.++### BRAIN-FUT-006 β Active-preference injection via per-turn hook++**Trigger to pull forward:**+- β₯10 confirmed preferences in `Brain/preferences/`, AND+- Observed cases where the agent did not apply a relevant active preference in a task despite the `brain-memory` skill being loaded.++**Dependencies:** v0.9 ships. Reuses existing Hermes `pre_llm_call` channel, Claude Code system-prompt prepend, and Codex pre-message hook.++**Scope sketch:**+- A shared module (per-runtime plugin, e.g. `~/.hermes/plugins/brain-preference-injector/`) reads `Brain/preferences/` filtered to `status: confirmed` and to scopes matching the current task topic; injects a compact summary into the per-turn system prompt.+- Hard token budget on the injection (e.g. 500 tokens) to avoid context-window bloat.+- Pinned preferences ordered first; high-confidence next; remainder may be elided if over budget.++**Why deferred:** with zero confirmed preferences the injection is empty. Even with a few, the noise-to-signal ratio is unfavourable. The trigger waits until the injection actually carries useful content.++## Integration++### BRAIN-FUT-007 β OpenClaw native JS parity for Brain tools++**Trigger to pull forward:** v0.9 has shipped and is actively used in at least one runtime; the OpenClaw runtime is part of the user's working set (i.e., real demand exists).++**Dependencies:** v0.9 stable.++**Scope sketch:**+- Mirror all 6 MCP `brain_*` tools as pure JavaScript in `openclaw/brain.js`.+- No subprocess (OpenClaw security scanner requirement).+- Reuse the pure-JS frontmatter parser already in `openclaw/vault.js`.+- Atomic-write parity using `node:fs/promises`.++**Why deferred:** dual TS+JS maintenance is real ongoing cost. Wait until v0.9 is genuinely used; if OpenClaw runtime is not adopted, parity may never need to ship.++### BRAIN-FUT-008 β Pay Memory β Brain bridge++**Trigger to pull forward:** at least one paid action recorded by Pay Memory has touched, or would have benefited from, a budget-related preference (e.g., "avoid image generation above $0.05 for blog drafts").++**Dependencies:** v0.9 ships. Pay Memory continues to function unchanged.++**Scope sketch:**+- After a paid call lands and a Pay Memory receipt is written, an opt-in flag in Pay Memory config triggers emission of a `brain_feedback` signal with `scope: paid-action` and the cost embedded in the principle context.+- Over time, `dream` surfaces preferences like "avoid paysponge/fal above $X for media-generation" automatically.+- No coupling: Pay Memory does not require Brain; Brain does not require Pay Memory. The bridge is fully opt-in.++**Why deferred:** the bridge is cheap to implement but only valuable if Pay Memory is in active use. v0.9 ships Brain independent of payments; the bridge is a small follow-up.++## Lifecycle++### BRAIN-FUT-009 β Hard removal of deprecated legacy write paths++**Trigger to pull forward:**+- Brain has been in productive use for a sustained activity volume in `Brain/log/`, AND+- No agent or user has called the legacy `event_log_append` or `second_brain_capture` MCP tools in that volume (verified by absence of corresponding handler invocations in any session telemetry), AND+- No CHANGELOG entry or design doc references the legacy paths as still required.++**Dependencies:** v0.9 + the soft deprecation in v0.9.x must be stable.++**Scope sketch:**+- Remove `src/core/event-log.ts` writer functions (keep readers if still referenced by `second_brain_query`).+- Remove `src/mcp/handlers/event_log_append.ts` and `src/mcp/handlers/second_brain_capture.ts`.+- Remove CLI verbs `o2b append-event`, `vault-log` symlink, and the legacy AI Wiki bootstrap inside `o2b init`.+- Remove `docs/legacy-skills/` directory.+- Update CHANGELOG and bump to a new minor version (the removal is a public-API change).++**Why deferred:** soft deprecation in v0.9 leaves the code intact precisely so we can revisit if real usage shows the deprecation was premature. Wait for affirmative evidence that the legacy paths are truly unused before deleting.++### BRAIN-FUT-010 β High-confidence preference codification into `brain-memory` skill++**Trigger to pull forward:**+- β₯5 confirmed preferences with `confidence: high` and `applied_count` β₯ 20, AND+- BRAIN-FUT-006 has shipped and produced observable token-cost data for the per-turn injection, AND+- That cost is non-trivial relative to per-task budgets.++**Dependencies:** BRAIN-FUT-006.++**Scope sketch:**+- A semi-manual operation: `o2b brain skill-codify` selects the top-N most-applied high-confidence preferences and regenerates `skills/brain-memory/SKILL.md` body to include them as fixed agent knowledge.+- This converts "live preferences" into "permanent skill content", aligning with the "fat skill, thin harness" pattern. Reduces per-turn injection cost.+- The original preferences stay in Brain (now redundant with the skill, but kept as the audit trail and the source of truth if the skill is regenerated).++**Why deferred:** speculative. Requires BRAIN-FUT-006 first to have real cost data; without it, the codification is solving a non-problem.++## Removed / superseded++(none yet)++When an item is dropped because the underlying need disappeared or the design was fundamentally rethought, add it here with a one-line note explaining why, and keep its ID retired. Example shape:++```text+- **BRAIN-FUT-NNN** β Title. Removed because <reason>. See <link to discussion or replacement plan>.+```++## References++- v0.9.0 design doc: `docs/plans/2026-05-15-brain-observing-memory.md`. The starting point this roadmap defers items from.+- Prior plans for shape reference: `docs/plans/2026-05-06-cli-foundation.md`, `docs/plans/2026-05-10-pay-memory.md`. Useful when an item moves out into its own design doc.diff --git a/hooks/hooks.json b/hooks/hooks.jsonindex 4f1a68f5..9c32dc13 100644--- a/hooks/hooks.json+++ b/hooks/hooks.json@@ -8,19 +8,7 @@"type": "command","command": "o2b-hook post-write-reminder","timeout": 10,- "statusMessage": "OSB: reminding to log"- }- ]- }- ],- "Stop": [- {- "hooks": [- {- "type": "command",- "command": "o2b-hook stop-log-guardrail",- "timeout": 15,- "statusMessage": "OSB: checking event log"+ "statusMessage": "OSB: reminding to log signals/evidence"}]}diff --git a/hooks/lib/messages.ts b/hooks/lib/messages.tsindex de6040fa..0c30627f 100644--- a/hooks/lib/messages.ts+++ b/hooks/lib/messages.ts@@ -23,14 +23,19 @@ export function postWriteReminder({ toolName, filePath }: PostWriteReminderInputreturn [`Open Second Brain hook: you just ran \`${toolName}\` against ${target}.`,"",- "If this change is a durable artifact (code shipped, config or",- "deployment change, instruction-file edit, content artifact,",- "research / investigation finding, or external-fact discovery),",- "call `event_log_append` before you finish this turn.",+ "If this turn contained a user preference, correction, or rule that",+ "should outlast the current task (\"don't do X\", \"prefer Y\", \"use",+ "A instead of B\"), call `brain_feedback` once per signal to record",+ "it into `Brain/inbox/`.","",- "If it is trivial (typo fix, formatting, intermediate scratch),",- "no log is needed β just finish your reply and the Stop guardrail",- "will not block you a second time.",+ "If a confirmed or unconfirmed preference in `Brain/preferences/`",+ "scopes to the artifact you just produced, call",+ "`brain_apply_evidence` with `result: applied | violated` so the",+ "dream pass can update confidence and retire stale rules.",+ "",+ "Trivial edits (typo fix, pure formatting) don't need either call.",+ "A misrecorded signal is worse than a missed one β skip when not",+ "confident; the dream pass will pick up patterns from repeats.",].join("\n");}diff --git a/install.md b/install.mdindex bb0eed7a..b2948784 100644--- a/install.md+++ b/install.md@@ -16,7 +16,7 @@ If at any point you are missing information β for example, the vault path is u## Prerequisites β Bun runtime (all branches)-**Open Second Brain v0.7+ runs on the [Bun](https://bun.sh) JavaScript runtime.** The `o2b` CLI, the MCP server (`o2b mcp`), and the OpenClaw native plugin all execute under Bun. Hermes still loads a small Python shim for the per-turn `pre_llm_call` hook, but every other runtime path is Bun-only.+**Open Second Brain runs on the [Bun](https://bun.sh) JavaScript runtime.** The `o2b` CLI, the MCP server (`o2b mcp`), and the OpenClaw native plugin all execute under Bun. Hermes still loads a small Python shim for the per-turn `pre_llm_call` hook, but every other runtime path is Bun-only.**Before running any branch below, verify Bun is on PATH:**@@ -33,7 +33,7 @@ bun --version`bun --version` must report **1.1.0 or newer**. If it does not, stop and ask the user to upgrade Bun before continuing β older versions miss APIs the plugin relies on.-If the user is on a system where they cannot install Bun (locked-down environment, unsupported architecture), abort the install and tell them so explicitly. Do **not** try to work around the missing runtime by re-exporting Python sources β those were removed in v0.7.0 and there is no Python fallback for the CLI.+If the user is on a system where they cannot install Bun (locked-down environment, unsupported architecture), abort the install and tell them so explicitly. There is no Python fallback for the CLI; do **not** try to work around the missing runtime by hand-rolling one.---@@ -178,6 +178,11 @@ with the values collected in step 1.o2b init --vault /path/to/vault --name "My Second Brain" \--agent-name "<chosen-agent-name>" \--timezone "<chosen-timezone>"++# Recommended on v0.9.0+: bootstrap the Brain observing-memory layer+# next to AI Wiki/. Idempotent; safe to skip on first install if the+# user explicitly opts out of Brain.+o2b brain init --vault /path/to/vault````--agent-name` writes the chosen name into `AI Wiki/identity/agents.md`@@ -187,6 +192,30 @@ IANA name via stdlib `zoneinfo` and persists it to the same config; fromthat moment on, every `event_log_append` call stamps Daily entries inthat timezone regardless of the host's clock.+**Wire the `brain-memory` skill into the default Hermes profile.** The+plugin ships `skills/brain-memory/SKILL.md`, which tells the agent when+to call `brain_feedback` / `brain_apply_evidence` in conversation β+without it the MCP tools are registered but the agent does not know to+proactively use them. If the user has a `hermes-skills-sync` helper+configured (typical on systems following the `/root/.agents/` skill+convention), enable the skill once:++```bash+ln -sfn "$(hermes plugins inspect open-second-brain --plugin-root)/skills/brain-memory" \+ /root/.agents/hermes-skills-pool/.agents/skills/brain-memory+/root/.agents/hermes-skills-sync enable <profile-name> brain-memory+hermes gateway restart+```++`<profile-name>` is the Hermes profile your default gateway inherits+(commonly `product-tech-lead` per local convention). If the system does+not use that convention, simply expose the skill anywhere Hermes scans+(`/root/.agents/skills/` is global; per-profile views live under+`/root/.agents/hermes-skillsets/<profile>/`). After `hermes skills list`+shows `brain-memory β enabled`, the agent will start recognising+preference signals in conversation and writing them through+`brain_feedback`.+### 5. Register the MCP server**Recommended path β edit `~/.hermes/config.yaml` directly.** Add the@@ -408,6 +437,11 @@ with the values collected in step 1.o2b init --vault /path/to/vault --name "My Second Brain" \--agent-name "<chosen-agent-name>" \--timezone "<chosen-timezone>"++# Recommended on v0.9.0+: bootstrap the Brain observing-memory layer+# next to AI Wiki/. Idempotent; safe to skip on first install if the+# user explicitly opts out of Brain.+o2b brain init --vault /path/to/vault````--agent-name` writes the chosen name into `AI Wiki/identity/agents.md`@@ -606,11 +640,20 @@ enabled = true(The `<plugin>@<marketplace>` form here resolves to plugin`open-second-brain` from marketplace `open-second-brain` β both names-come from the manifest.) The plugin's MCP tools (`event_log_append`,-`second_brain_capture`, `second_brain_query`, `second_brain_status`,-`vault_health`) become available **only** after step 5 below β Codex-treats MCP server registration as a separate concern from plugin-enablement.+come from the manifest.) The plugin's advertised MCP tools become+available **only** after step 5 below β Codex treats MCP server+registration as a separate concern from plugin enablement. The+advertised set is:++- **Core (3):** `second_brain_status`, `second_brain_query`,+ `vault_health`.+- **Brain (6):** `brain_feedback`, `brain_dream`,+ `brain_apply_evidence`, `brain_digest`, `brain_query`,+ `brain_doctor`.+- **Pay Memory (8):** `payment_memory_init`, `payment_receipt_append`,+ `asset_capture`, `payment_report_generate`, `payment_policy_check`,+ `payment_request_approval`, `payment_request_status`,+ `payment_request_consume`.### 3. Publish CLI commands to PATH@@ -638,6 +681,11 @@ with the values collected in step 1.o2b init --vault /path/to/vault --name "My Second Brain" \--agent-name "<chosen-agent-name>" \--timezone "<chosen-timezone>"++# Recommended on v0.9.0+: bootstrap the Brain observing-memory layer+# next to AI Wiki/. Idempotent; safe to skip on first install if the+# user explicitly opts out of Brain.+o2b brain init --vault /path/to/vault````--timezone` validates the IANA name via stdlib `zoneinfo` and persists@@ -690,17 +738,18 @@ until that check passes.### 6b. Lifecycle hooks (auto-enabled)The plugin ships a `hooks/hooks.json` that Codex loads automatically-from the bundled plugin tree. Two hooks fire per turn:+from the bundled plugin tree. One hook fires per turn:-- `PostToolUse` (matcher `Write|Edit|MultiEdit|apply_patch`) β reminds- the agent to call `event_log_append` when a durable artifact landed.-- `Stop` β blocks the turn at most once if the agent produced an- artifact but did not log. The next Stop passes through, so the agent- decides whether to log or just finish.+- `PostToolUse` (matcher `Write|Edit|MultiEdit|apply_patch`) β after+ a file-mutating tool succeeds, injects a short reminder pointing+ the agent at `brain_feedback` (when the turn contained a user+ preference or correction) and `brain_apply_evidence` (when an+ active preference in `Brain/preferences/` scopes to the artifact+ just produced).-Both hooks invoke `o2b-hook` from PATH. That CLI was symlinked into+The hook invokes `o2b-hook` from PATH. That CLI was symlinked into`~/.local/bin` by step 3, so no extra wiring is needed. If-`o2b-hook` is missing from PATH the hooks fail closed (turn proceeds+`o2b-hook` is missing from PATH the hook fails closed (turn proceedsnormally with a stderr trace) β re-run step 3 to fix.### 7. Update@@ -867,6 +916,11 @@ with the values collected in step 1.o2b init --vault /path/to/vault --name "My Second Brain" \--agent-name "<chosen-agent-name>" \--timezone "<chosen-timezone>"++# Recommended on v0.9.0+: bootstrap the Brain observing-memory layer+# next to AI Wiki/. Idempotent; safe to skip on first install if the+# user explicitly opts out of Brain.+o2b brain init --vault /path/to/vault````o2b init` persists all three values (`vault`, `agent_name`, `timezone`)@@ -900,19 +954,20 @@ below). Installation is incomplete until that check passes.### 6b. Lifecycle hooks (auto-enabled)The plugin ships a `hooks/hooks.json` that Claude Code loads-automatically from the cached plugin tree. Two hooks fire per turn:+automatically from the cached plugin tree. One hook fires per turn:-- `PostToolUse` (matcher `Write|Edit|MultiEdit|apply_patch`) β reminds- the agent to call `event_log_append` when a durable artifact landed.-- `Stop` β blocks the turn at most once if the agent produced an- artifact but did not log. The next Stop passes through, so the agent- decides whether to log or just finish.+- `PostToolUse` (matcher `Write|Edit|MultiEdit|apply_patch`) β after+ a file-mutating tool succeeds, injects a short reminder pointing+ the agent at `brain_feedback` (when the turn contained a user+ preference or correction) and `brain_apply_evidence` (when an+ active preference in `Brain/preferences/` scopes to the artifact+ just produced).-Both hooks invoke `o2b-hook` from PATH. That CLI was symlinked into+The hook invokes `o2b-hook` from PATH. That CLI was symlinked into`~/.local/bin` by step 3, so no extra wiring is needed. To watch the-hooks fire end-to-end use `--output-format=stream-json --verbose+hook fire end-to-end use `--output-format=stream-json --verbose--include-hook-events`; you should see `hook_started` /-`hook_response` events around each `Write` / `Edit` and around `Stop`.+`hook_response` events around each `Write` / `Edit`.### 7. Update@@ -959,9 +1014,12 @@ The plugin's runtime contract is small:- The `o2b` CLI on PATH (used for vault scaffolding, status, anddoctor checks).- The `o2b mcp` stdio server registered with the runtime as an MCP- server (used by the LLM at runtime via the five tools- `event_log_append` / `second_brain_capture` / `second_brain_query` /- `second_brain_status` / `vault_health`).+ server. The advertised tool set is 17 tools across three groups+ β Core (3: `second_brain_status` / `second_brain_query` /+ `vault_health`), Brain (6: `brain_feedback` / `brain_dream` /+ `brain_apply_evidence` / `brain_digest` / `brain_query` /+ `brain_doctor`), and Pay Memory (8: `payment_*` and+ `asset_capture`).- A persisted plugin config at `~/.config/open-second-brain/config.yaml`holding `vault` / `agent_name` / `timezone` (written by `o2b init`,read by `o2b mcp` when its CLI flags / env vars are absent).@@ -1005,6 +1063,11 @@ a content-addressed path with a version hash, glob it:o2b init --vault /path/to/vault --name "My Second Brain" \--agent-name "<chosen-agent-name>" \--timezone "<chosen-timezone>"++# Recommended on v0.9.0+: bootstrap the Brain observing-memory layer+# next to AI Wiki/. Idempotent; safe to skip on first install if the+# user explicitly opts out of Brain.+o2b brain init --vault /path/to/vault```This is identical across runtimes β the values are persisted intodiff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 565c7edf..aeb74aa7 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.8.1",+ "version": "0.9.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex 8b231172..c95bbb1d 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.8.1",+ "version": "0.9.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 760fb92b..63776787 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.8.1"+version: "0.9.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 58780d34..fe68f172 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.8.1",+ "version": "0.9.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 41592461..5a823bc6 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.8.1"+version: "0.9.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 cc84ed90..da7b4fb2 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.8.1"+version = "0.9.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/skills/brain-memory/SKILL.md b/skills/brain-memory/SKILL.mdnew file mode 100644index 00000000..f23b207b--- /dev/null+++ b/skills/brain-memory/SKILL.md@@ -0,0 +1,103 @@+---+name: brain-memory+description: Record taste signals and apply-evidence events into the Brain observing-memory layer of Open Second Brain. INVOKE this skill (and call `brain_feedback`) the moment the user expresses a preference, dislike, correction, or rule in dialogue β "don't do X", "use A instead of B", "I prefer Y", "X is wrong here", or any explicit imperative that should outlive the current turn. SEPARATELY invoke (and call `brain_apply_evidence`) right after you produce a durable artifact (code shipped, file written, content drafted, config change) and at least one preference in `Brain/preferences/` has a `scope` that plausibly applies β record whether you `applied` or `violated` it. SKIP for casual chat, exploration without a stated rule, read-only inspection, trivial edits, and any case where you are not confident a preference applies. WRITE the `principle` and `note` fields in the same natural language the user has been speaking in this session; technical identifiers (`topic` slug, `pref_id`, `scope`) stay English. A misrecorded signal is worse than a missed one β the dream pass eventually surfaces real patterns from repeat events, so prefer precision over coverage.+---++# Brain Memory++Brain is the agent-writable observing-memory layer of Open Second Brain. It accumulates user preferences from real signals and learns from real applications. Your job is to (a) record taste signals as they arrive in conversation, and (b) record whether you applied or violated active preferences each time you produce a durable artifact in a relevant scope. The deterministic `dream` pass turns repeat signals into rules and retires what stops being applied.++## When to call `brain_feedback`++Call **once per taste signal** the user (or a teammate agent) expresses. Concrete triggers:++- Explicit corrections: "don't do X", "stop doing Y", "use A instead of B".+- Stated preferences with outlasting reach: "I prefer X over Y", "expand acronyms on first use", "always include a CHANGELOG entry".+- Pushback on a specific artifact you produced that targets a *rule*, not a one-off ("this commit message is wrong β use imperative voice").+- A teammate agent or human describing a process rule in chat that should survive future sessions.++Parameters:++- `topic`: stable kebab-slug for the rule (`no-internal-abbrev`, `imperative-prompts`, `prefer-typed-errors`). Reuse existing slugs β call `brain_query --topic <slug>` first if you are unsure. New slugs only when no existing one fits.+- `signal`: `positive` when the principle stated is the rule to follow, `negative` when the principle stated is what to avoid.+- `principle`: one-line, imperative-voice agent-readable formulation. "Do not use internal abbreviations in user-facing copy unless explained first."+- `agent`: your runtime identity (`claude`, `codex`, `hermes`, OpenClaw plugin name, or the human's name if you are recording on their behalf).++Optional:++- `scope`: soft category for later application-scope matching β `writing`, `coding`, `process`, `design`, `infra`, `docs`. Pick the narrowest accurate one.+- `source`: array of wikilinks to the artifacts or notes that triggered the signal β `[[Daily/2026.05.14]]`, `[[blog-header-draft]]`. Improves later auditability.++The server creates `Brain/inbox/sig-<date>-<slug>.md` and resolves collisions deterministically.++## When to call `brain_apply_evidence`++Call **once per (preference, artifact) pair**, right after a durable artifact lands. A durable artifact is anything the user would re-find by searching the vault tomorrow: code shipped, config change, deployment touched, content drafted, instruction-file edit, design decision recorded. Trivial edits (typo fix, pure formatting) do not qualify.++Discover applicable preferences first. Options:++- Read `Brain/preferences/` directly β files `pref-*.md` are tiny.+- Call `brain_query --topic <slug>` to fetch a topic-scoped slice.+- Call `brain_query --preference <id>` for a single preference plus its evidence trail.++Parameters:++- `pref_id`: id of the preference you are recording against (`pref-no-internal-abbrev`).+- `artifact`: wikilink identifying what you produced β `[[Daily/2026.05.14#section-blog-post]]`, `[[src/cli/main.ts]]`, `[[docs/release-notes/v0.9.0.md]]`. The wikilink resolves in Obsidian; use `#anchor` to point at a specific section when relevant.+- `result`: `applied` if the rule held in this artifact, `violated` if you (or another agent) broke it. Recording a `violated` event is not a failure β it is what trains the system.+- `agent`: your runtime identity.++Optional:++- `note`: one-line context if useful ("expanded 'OSB' to 'Open Second Brain' on first use", "README diff still contained unexplained 'FT'").++`applied_count` and `violated_count` on the preference are recomputed by `dream`; you write only the per-event evidence record.++## When NOT to call++- Casual chat, banter, acknowledgements ("ok", "got it").+- Brainstorming, idea exploration, design discussion that has not concluded in a rule.+- Read-only inspection (running `git log`, `o2b status`, `vault_health`).+- Trivial edits (typo, whitespace, formatting only).+- Cases where a preference *might* apply but you are not confident β skip rather than fabricate a match.++A false-positive signal eventually distorts the rule set; a missed signal is recovered on repeat. Prefer precision.++## Language++The `principle` and `note` fields must match the **natural language the user has been speaking in this session**. Technical identifiers stay English regardless: `topic` slug, `scope`, `pref_id`, `result`, `agent` name, file paths, library names, error messages quoted from logs. This mirrors the policy from the `agent-event-log` skill.++Mixed-language session β match the most recent user message at the time the artifact landed.++## Self-discovery++- `brain_query --preference pref-foo` β full preference frontmatter + every evidence record in `Brain/log/*` referencing it.+- `brain_query --topic <slug>` β all artifacts (signals, current preference, retired ones) by topic.+- `brain_query --since <ISO>` β recent log events of any type.+- `brain_digest` β daily summary of what `dream` did: new unconfirmed, confirmations, retirements, confidence shifts, contradictions.++## CLI fallback++When MCP is unavailable:++```bash+o2b brain feedback \+ --topic no-internal-abbrev \+ --signal negative \+ --principle "Do not use internal abbreviations in user-facing copy unless explained first" \+ --agent claude++o2b brain apply-evidence \+ --pref pref-no-internal-abbrev \+ --artifact "[[Daily/2026.05.14#blog-post]]" \+ --result applied \+ --agent claude+```++## Rules++- One call per signal, one call per (preference, artifact) pair.+- Imperative voice in `principle`. Specific over generic.+- Never include secrets, tokens, API keys, or credentials in `principle`, `note`, or `source`.+- Do not edit historical signals, preferences, or log entries by hand β the `dream` pass is the only writer for transitions.+- Do not write into `Brain/.snapshots/` or `Brain/retired/` directly β those are managed by `dream` and `o2b brain reject` only.diff --git a/skills/open-second-brain/SKILL.md b/skills/open-second-brain/SKILL.mdindex 6565a3ab..73a822b2 100644--- a/skills/open-second-brain/SKILL.md+++ b/skills/open-second-brain/SKILL.md@@ -1,32 +1,43 @@---name: open-second-brain-description: Use Open Second Brain to read, write, and maintain an agent-owned second brain in an Obsidian-compatible Markdown vault.+description: Use Open Second Brain to read, write, and maintain an agent-owned second brain in an Obsidian-compatible Markdown vault. The writable agent-facing surface is the `Brain/` layer (see the `brain-memory` skill for signal/evidence recording). `AI Wiki/` and `Daily/` are read surfaces; Pay Memory is a separate orthogonal layer for paid-action audit.---# Open Second BrainUse this skill when a user asks an agent to use, configure, inspect, or maintain Open Second Brain.+## Layers++Open Second Brain organises the vault into three agent-facing layers. Know which one to touch and when.++- **`Brain/`** β agent-writable observing memory. Taste signals, accreted preferences (unconfirmed β confirmed β retired), evidence log, snapshots. This is where you record what the user prefers and how you applied those preferences in real work. Operations go through MCP tools `brain_feedback`, `brain_apply_evidence`, `brain_dream`, `brain_digest`, `brain_query`, `brain_doctor` β see the `brain-memory` skill for the calling protocol. CLI counterparts: `o2b brain *` (11 verbs).+- **`AI Wiki/`** and **`Daily/`** β read surfaces. `AI Wiki/` holds identity files, index/hot list, system snapshots, and the Pay Memory subtree. `Daily/` holds the chronological event log and human narrative. Read through `second_brain_query` and `vault_health`. Brain operations do not write here; the only writes into `AI Wiki/` come from the Pay Memory tools (next bullet).+- **Pay Memory** β orthogonal audit layer for paid agent actions (`AI Wiki/payments/`, `assets/`, `drafts/`, `reports/`, `policies/`). Agents use `payment_*` MCP tools when they make paid API calls. Pay Memory operates independently of Brain.+## Core principles- Treat the vault as user-owned durable knowledge.-- Write only inside configured agent-owned areas unless explicitly instructed.-- Keep raw operational events separate from synthesized knowledge.+- Write only into the `Brain/` layer (signals and evidence) or, for paid actions, into the Pay Memory subtree under `AI Wiki/`. Do not write into `AI Wiki/notes/`, `AI Wiki/identity/`, `Daily/`, or any non-Pay-Memory area under `AI Wiki/`.+- Keep raw operational evidence separate from synthesized knowledge: per-event records go to `Brain/log/`, preferences live in `Brain/preferences/`.- Never write secrets, tokens, passwords, private keys, or credential-bearing connection strings.-- Prefer deterministic CLI commands over guessing file paths.--## v0 expectation--In v0, Open Second Brain is expected to provide documentation, scripts, skills, and plugin manifests. Deep runtime automation and MCP tools are future work.+- Prefer deterministic CLI commands (`o2b brain ...`, `o2b doctor`, `o2b status`) over guessing file paths.## Default workflow-1. Check whether Open Second Brain is configured.-2. Read the machine-local config if available.-3. Read the vault-local operating manual if available.-4. Use `vault-log` or `o2b append-event` for event logging.-5. Use Markdown edits for durable synthesized knowledge only when the user asks or the configured policy allows it.+1. Check whether Open Second Brain is configured: `o2b status` or `second_brain_status` MCP tool.+2. Read the machine-local config if available (vault path, agent identity, timezone).+3. Read the vault-local operating manual `Brain/_BRAIN.md` β this is the per-vault contract for agents.+4. Record taste signals as they arrive in dialogue via `brain_feedback` (see the `brain-memory` skill).+5. After producing a durable artifact, check applicable preferences and record evidence via `brain_apply_evidence` (see the `brain-memory` skill).+6. For read access to `AI Wiki/` or `Daily/` content, use `second_brain_query`.## Safety-If a write operation might affect personal notes outside the agent-owned area, ask for explicit confirmation.+If a write operation might affect personal notes or anything outside the `Brain/` layer (and not Pay Memory), ask for explicit confirmation. When in doubt, prefer `Brain/`.++## See also++- `brain-memory` skill β when and how to call `brain_feedback` / `brain_apply_evidence`.+- `Brain/_BRAIN.md` (in each vault) β operating manual for that vault, generated by `o2b brain init`.+- `docs/plans/2026-05-15-brain-observing-memory.md` (in the repo) β full design.diff --git a/src/cli/brain.ts b/src/cli/brain.tsnew file mode 100644index 00000000..b5b916d6--- /dev/null+++ b/src/cli/brain.ts@@ -0,0 +1,1101 @@+/**+ * `o2b brain` subcommand dispatcher.+ *+ * Routes the eleven Brain verbs (design doc Β§9.2) to thin wrappers over+ * `src/core/brain/*`. The core modules own all I/O and business logic;+ * this file only parses flags, resolves the vault, and shapes the+ * exit-code matrix (0 success / 1 error / 2 informational not-found).+ *+ * Layout mirrors `src/cli/main.ts` β one `cmdBrain<Verb>` function per+ * verb, each returning a number that {@link handleBrainSubcommand} hands+ * back to the outer dispatcher.+ *+ * State-changing verbs print a single human-readable line on stdout.+ * Read-only verbs (digest, query, doctor) honour `--json`. The `--json`+ * flag on state-changing verbs (init/feedback/apply-evidence/...) emits a+ * minimal `{ok: true, ...}` summary so scripted callers can still pin on+ * structured output.+ *+ * Pinning / unpinning / reject / pin / rollback / init are intentionally+ * CLI-only β the MCP surface in Task 7 does not expose them so an+ * autonomous agent cannot mutate the protected set, retire rules+ * unilaterally, or overwrite the vault from a snapshot.+ */++import { existsSync, readFileSync, readdirSync, statSync, type Dirent } from "node:fs";+import { resolve } from "node:path";++import {+ defaultConfigPath,+ resolveAgentName,+ resolveVault,+} from "../core/config.ts";+import { bootstrapBrain } from "../core/brain/init.ts";+import {+ appendApplyEvidence,+ BrainPreferenceNotFoundError,+} from "../core/brain/apply-evidence.ts";+import { dream } from "../core/brain/dream.ts";+import { moveToRetired, parsePreference, writePreference } from "../core/brain/preference.ts";+import { preferencePath } from "../core/brain/paths.ts";+import { isoDate, isoSecond } from "../core/brain/time.ts";+import {+ queryByLogSince,+ queryByPreference,+ queryByTopic,+ BrainNotFoundError,+} from "../core/brain/query.ts";+import { renderDigest, type RenderDigestOptions } from "../core/brain/digest.ts";+import { runDoctor } from "../core/brain/doctor.ts";+import { setPinned } from "../core/brain/pin.ts";+import { writeSignal } from "../core/brain/signal.ts";+import { listSnapshots, restoreSnapshot } from "../core/brain/snapshot.ts";+import { appendLogEvent, type BrainLogEntry } from "../core/brain/log.ts";+import {+ BRAIN_LOG_EVENT_KIND,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_SIGNAL_SIGN,+} from "../core/brain/types.ts";+import { CliError, parseFlags, type FlagsSchema } from "./argparse.ts";++const NO_VAULT_ERROR =+ "error: no vault configured. Pass --vault <path> explicitly, " ++ "set VAULT_DIR in the environment, or run " ++ "`o2b init --vault <path> ...` first to persist a default.";++/**+ * Resolve a vault path from CLI flags or machine-local config. Throws a+ * {@link CliError} with the standard help message when neither source+ * supplies a value β the dispatcher converts this into exit code 1.+ */+function resolveBrainVault(+ flagVal: string | undefined,+ configPath: string | null,+): string {+ const vault = flagVal ?? resolveVault(configPath ?? undefined);+ if (vault === null || vault === undefined) {+ throw new CliError(NO_VAULT_ERROR);+ }+ return vault;+}++/** Emit a state-changing command's status line on stdout. */+function ok(line: string): void {+ process.stdout.write(line + (line.endsWith("\n") ? "" : "\n"));+}++/** Emit minimal JSON for `--json` on state-changing commands. */+function okJson(payload: Record<string, unknown>): void {+ process.stdout.write(JSON.stringify({ ok: true, ...payload }, null, 2) + "\n");+}++function fail(message: string): number {+ process.stderr.write(`error: ${message}\n`);+ return 1;+}++function info(message: string): void {+ process.stdout.write(message + (message.endsWith("\n") ? "" : "\n"));+}++/**+ * Strict ISO-8601 timestamp matcher used by `--now / --since / --until`.+ * The plain `new Date(s)` constructor is far too permissive (it happily+ * parses `"2026"`, `"hello world"` via some locales, year-only strings,+ * etc.). We require a full date-time including offset (`Z` or `Β±HH:MM`),+ * which is the shape `isoSecond()` emits and what scripted callers send.+ */+const ISO_8601_RE =+ /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/;++// ββ Common parse helpers ββββββββββββββββββββββββββββββββββββββββββββββββββββ++/**+ * Wrap `parseFlags` with a uniform failure path: bad flags surface as+ * `CliError` and the dispatcher converts those to exit code 1.+ */+function parse(+ argv: ReadonlyArray<string>,+ schema: FlagsSchema,+): {+ flags: Record<string, string | boolean | string[] | undefined>;+ positional: string[];+} {+ return parseFlags(argv, schema);+}++// ββ Verb handlers βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++async function cmdBrainInit(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ config: { type: "string" },+ force: { type: "boolean" },+ json: { type: "boolean" },+ });+ const config = (flags["config"] as string | undefined) ?? defaultConfigPath();+ // `bootstrapBrain` itself refuses without a registered machine config;+ // resolve the vault from flag-or-config so a freshly registered machine+ // can run `o2b brain init` without restating `--vault`.+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ let result;+ try {+ result = bootstrapBrain(vault, {+ force: Boolean(flags["force"]),+ configPath: config,+ });+ } catch (exc) {+ return fail(`failed to initialize Brain: ${(exc as Error).message ?? exc}`);+ }++ if (flags["json"]) {+ okJson({+ vault,+ created: result.created,+ overwritten: result.overwritten,+ skipped: result.skipped,+ });+ return 0;+ }+ ok(`brain initialized: ${vault}`);+ for (const p of result.created) info(` created: ${p}`);+ for (const p of result.overwritten) info(` overwritten: ${p}`);+ for (const p of result.skipped) info(` exists: ${p}`);+ return 0;+}++async function cmdBrainFeedback(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ topic: { type: "string" },+ signal: { type: "string" },+ principle: { type: "string" },+ scope: { type: "string" },+ source: { type: "string-array" },+ agent: { type: "string" },+ raw: { type: "string" },+ "raw-file": { type: "string" },+ "force-confirmed": { type: "boolean" },+ date: { type: "string" },+ slug: { type: "string" },+ json: { type: "boolean" },+ });++ // Required-flag enforcement is custom here so the error message names+ // the field β design doc Β§13.7 demands "missing required argument+ // exits 1 naming the field".+ for (const field of ["topic", "signal", "principle"] as const) {+ if (typeof flags[field] !== "string" || (flags[field] as string).trim() === "") {+ return fail(`brain feedback missing required flag: --${field}`);+ }+ }++ const signalSign = String(flags["signal"]);+ if (+ signalSign !== BRAIN_SIGNAL_SIGN.positive &&+ signalSign !== BRAIN_SIGNAL_SIGN.negative+ ) {+ return fail(+ `--signal must be 'positive' or 'negative'; got ${JSON.stringify(signalSign)}`,+ );+ }++ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);+ const agent = (flags["agent"] as string | undefined) ?? resolveAgentName(config);++ let raw: string | undefined;+ const rawFile = flags["raw-file"] as string | undefined;+ if (rawFile) {+ try {+ raw = readFileSync(rawFile, "utf8");+ } catch (exc) {+ return fail(`cannot read --raw-file: ${(exc as Error).message ?? exc}`);+ }+ } else if (flags["raw"]) {+ raw = String(flags["raw"]);+ }++ const now = new Date();+ const date = (flags["date"] as string | undefined) ?? isoDate(now);+ const slug = (flags["slug"] as string | undefined) ?? String(flags["topic"]);++ // 1. Always write the signal to inbox/. (Β§9.2: feedback always creates+ // `sig-*`; `--force-confirmed` ADDITIONALLY creates a confirmed pref.)+ let sigResult;+ try {+ sigResult = writeSignal(vault, {+ topic: String(flags["topic"]),+ signal: signalSign as "positive" | "negative",+ agent,+ principle: String(flags["principle"]),+ created_at: now.toISOString(),+ date,+ slug,+ ...(flags["scope"] ? { scope: String(flags["scope"]) } : {}),+ ...(flags["source"]+ ? { source: flags["source"] as string[] }+ : {}),+ ...(raw !== undefined ? { raw } : {}),+ });+ } catch (exc) {+ return fail(`failed to write signal: ${(exc as Error).message ?? exc}`);+ }++ // Emit a feedback log event so the dream loop can later attribute the+ // signal (and pin / unpin parity stays neat: every state-changing CLI+ // verb leaves a breadcrumb).+ try {+ appendLogEvent(vault, {+ timestamp: isoSecond(now),+ eventType: BRAIN_LOG_EVENT_KIND.feedback,+ body: {+ signal: `[[${sigResult.id}]]`,+ topic: String(flags["topic"]),+ sign: signalSign,+ agent,+ },+ });+ } catch (err) {+ // Log-event failure is non-fatal: the signal is already on disk and+ // the next dream pass will pick it up via filesystem scan. Surface+ // a warning so the audit trail gap is at least visible to the+ // operator.+ process.stderr.write(+ `warning: append feedback log failed: ${(err as Error).message}\n`,+ );+ }++ // 2. Optional escape hatch β `--force-confirmed` jumps the loop and+ // creates a `pref-*` directly in `status: confirmed`.+ let prefResult: { path: string; id: string } | null = null;+ if (flags["force-confirmed"]) {+ try {+ prefResult = writePreference(+ vault,+ {+ slug,+ topic: String(flags["topic"]),+ principle: String(flags["principle"]),+ created_at: now.toISOString(),+ unconfirmed_until: now.toISOString(),+ confirmed_at: now.toISOString(),+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [`[[${sigResult.id}]]`],+ ...(flags["scope"] ? { scope: String(flags["scope"]) } : {}),+ },+ { overwrite: false },+ );+ } catch (exc) {+ return fail(+ `failed to force-confirm preference: ${(exc as Error).message ?? exc}`,+ );+ }+ try {+ appendLogEvent(vault, {+ timestamp: isoSecond(new Date(now.getTime() + 1000)),+ eventType: BRAIN_LOG_EVENT_KIND.forceConfirmed,+ body: {+ preference: `[[${prefResult.id}]]`,+ agent,+ },+ });+ } catch (err) {+ // Non-fatal: the preference is already on disk; surface so the+ // gap in the audit trail is at least visible.+ process.stderr.write(+ `warning: append force-confirmed log failed: ${(err as Error).message}\n`,+ );+ }+ }++ if (flags["json"]) {+ okJson({+ signal_path: sigResult.path,+ signal_id: sigResult.id,+ ...(prefResult+ ? { preference_path: prefResult.path, preference_id: prefResult.id }+ : {}),+ });+ return 0;+ }+ ok(`signal: ${sigResult.path}`);+ ok(`id: ${sigResult.id}`);+ if (prefResult) {+ ok(`preference: ${prefResult.path}`);+ ok(`status: confirmed`);+ }+ return 0;+}++async function cmdBrainDream(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ "dry-run": { type: "boolean" },+ now: { type: "string" },+ json: { type: "boolean" },+ });+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ let now: Date | undefined;+ const nowStr = flags["now"] as string | undefined;+ if (nowStr) {+ if (!ISO_8601_RE.test(nowStr)) {+ return fail(`--now must be a valid ISO-8601 timestamp; got ${nowStr}`);+ }+ const parsed = new Date(nowStr);+ if (!Number.isFinite(parsed.getTime())) {+ return fail(`--now must be a valid ISO-8601 timestamp; got ${nowStr}`);+ }+ now = parsed;+ }++ let summary;+ try {+ summary = dream(vault, {+ ...(now !== undefined ? { now } : {}),+ dryRun: Boolean(flags["dry-run"]),+ });+ } catch (exc) {+ return fail(`dream failed: ${(exc as Error).message ?? exc}`);+ }++ if (flags["json"]) {+ process.stdout.write(JSON.stringify(summary, null, 2) + "\n");+ return 0;+ }+ ok(`run_id: ${summary.run_id}`);+ ok(`changed: ${summary.changed}`);+ if (summary.new_unconfirmed.length > 0) {+ ok(`new_unconfirmed: ${summary.new_unconfirmed.join(", ")}`);+ }+ if (summary.confirmed.length > 0) {+ ok(`confirmed: ${summary.confirmed.join(", ")}`);+ }+ if (summary.retired.length > 0) {+ ok(+ `retired: ${summary.retired.map((r) => `${r.id} (${r.reason})`).join(", ")}`,+ );+ }+ if (summary.contradictions.length > 0) {+ ok(`contradictions: ${summary.contradictions.join(", ")}`);+ }+ if (summary.moved_to_processed.length > 0) {+ ok(`moved_to_processed: ${summary.moved_to_processed.length}`);+ }+ return 0;+}++async function cmdBrainApplyEvidence(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ pref: { type: "string" },+ artifact: { type: "string" },+ result: { type: "string" },+ agent: { type: "string" },+ note: { type: "string" },+ json: { type: "boolean" },+ });+ for (const field of ["pref", "artifact", "result"] as const) {+ if (typeof flags[field] !== "string" || (flags[field] as string).trim() === "") {+ return fail(`brain apply-evidence missing required flag: --${field}`);+ }+ }+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);+ const agent = (flags["agent"] as string | undefined) ?? resolveAgentName(config);++ const resultStr = String(flags["result"]);+ if (resultStr !== "applied" && resultStr !== "violated") {+ return fail(`--result must be 'applied' or 'violated'; got ${resultStr}`);+ }++ try {+ const out = appendApplyEvidence(vault, {+ pref_id: String(flags["pref"]),+ artifact: String(flags["artifact"]),+ result: resultStr,+ agent,+ ...(flags["note"] ? { note: String(flags["note"]) } : {}),+ });+ if (flags["json"]) {+ okJson({ logged_at: out.logged_at, log_path: out.log_path });+ } else {+ ok(`logged: ${out.log_path}`);+ ok(`at: ${out.logged_at}`);+ }+ return 0;+ } catch (exc) {+ if (exc instanceof BrainPreferenceNotFoundError) {+ // Informative not-found per Β§9.2 β exit 2, not 1.+ process.stderr.write(`${exc.message}\n`);+ return 2;+ }+ return fail(`apply-evidence failed: ${(exc as Error).message ?? exc}`);+ }+}++async function cmdBrainDigest(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ since: { type: "string" },+ until: { type: "string" },+ json: { type: "boolean" },+ "silent-if-empty": { type: "boolean" },+ });+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ // Validate inputs before building the options literal so we never+ // materialise an `opts` object with NaN-time `Date`s. Strict ISO-8601+ // pattern check first so `--since 2026` / `--since "hello"` are rejected+ // before `new Date()` happily silently coerces them.+ let sinceDate: Date | undefined;+ if (flags["since"]) {+ const raw = String(flags["since"]);+ if (!ISO_8601_RE.test(raw)) {+ return fail(`--since must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ const d = new Date(raw);+ if (!Number.isFinite(d.getTime())) {+ return fail(`--since must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ sinceDate = d;+ }+ let untilDate: Date | undefined;+ if (flags["until"]) {+ const raw = String(flags["until"]);+ if (!ISO_8601_RE.test(raw)) {+ return fail(`--until must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ const d = new Date(raw);+ if (!Number.isFinite(d.getTime())) {+ return fail(`--until must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ untilDate = d;+ }+ const opts: RenderDigestOptions = {+ ...(sinceDate ? { since: sinceDate } : {}),+ ...(untilDate ? { until: untilDate } : {}),+ format: flags["json"] ? "json" : "markdown",+ };++ let result;+ try {+ result = renderDigest(vault, opts);+ } catch (exc) {+ return fail(`digest failed: ${(exc as Error).message ?? exc}`);+ }++ if (result.empty && flags["silent-if-empty"]) {+ // Β§8: exit 2 with no output. The CLI is the one place this matters+ // β scripts can branch on the exit code rather than parsing stdout.+ return 2;+ }+ process.stdout.write(result.content);+ if (!result.content.endsWith("\n")) process.stdout.write("\n");+ return 0;+}++async function cmdBrainQuery(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ preference: { type: "string" },+ topic: { type: "string" },+ since: { type: "string" },+ json: { type: "boolean" },+ });+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ // Mutually exclusive choice β pick one of the three query shapes.+ const modes = ["preference", "topic", "since"].filter(+ (k) => typeof flags[k] === "string" && (flags[k] as string).trim() !== "",+ );+ if (modes.length === 0) {+ return fail(+ "brain query requires exactly one of --preference, --topic, --since",+ );+ }+ if (modes.length > 1) {+ return fail(+ `brain query: pick only one of --preference / --topic / --since (got ${modes.join(", ")})`,+ );+ }++ try {+ if (flags["preference"]) {+ const out = queryByPreference(vault, String(flags["preference"]));+ if (flags["json"]) {+ process.stdout.write(JSON.stringify(out, null, 2) + "\n");+ } else {+ renderQueryPreferenceText(out);+ }+ return 0;+ }+ if (flags["topic"]) {+ const out = queryByTopic(vault, String(flags["topic"]));+ if (flags["json"]) {+ process.stdout.write(JSON.stringify(out, null, 2) + "\n");+ } else {+ renderQueryTopicText(out, String(flags["topic"]));+ }+ return 0;+ }+ if (flags["since"]) {+ const raw = String(flags["since"]);+ if (!ISO_8601_RE.test(raw)) {+ return fail(`--since must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ const d = new Date(raw);+ if (!Number.isFinite(d.getTime())) {+ return fail(`--since must be a valid ISO-8601 timestamp; got ${raw}`);+ }+ const entries = queryByLogSince(vault, d);+ if (flags["json"]) {+ process.stdout.write(JSON.stringify(entries, null, 2) + "\n");+ } else {+ renderQueryLogText(entries);+ }+ return 0;+ }+ } catch (exc) {+ if (exc instanceof BrainNotFoundError) {+ // Per Β§9.2 informational not-found: exit 2.+ process.stderr.write(`${exc.message}\n`);+ return 2;+ }+ return fail(`query failed: ${(exc as Error).message ?? exc}`);+ }+ return 0; // unreachable but keeps TypeScript happy+}++async function cmdBrainReject(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ id: { type: "string" },+ reason: { type: "string" },+ yes: { type: "boolean" },+ json: { type: "boolean" },+ });+ if (typeof flags["id"] !== "string" || (flags["id"] as string).trim() === "") {+ return fail("brain reject missing required flag: --id");+ }+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);+ const agent = resolveAgentName(config);++ // Resolve the preference file. If absent β exit 2 (informational+ // not-found per Β§9.2 pattern, consistent with apply-evidence).+ const rawId = String(flags["id"]).trim();+ const slug = rawId.startsWith("pref-") ? rawId.slice("pref-".length) : rawId;+ const path = preferencePath(vault, slug);+ if (!existsSync(path)) {+ process.stderr.write(+ `preference not found: pref-${slug}; expected ${path}\n`,+ );+ return 2;+ }+ let pref;+ try {+ pref = parsePreference(path);+ } catch (exc) {+ return fail(`failed to parse preference: ${(exc as Error).message ?? exc}`);+ }++ // Pin protection β refuse without --yes per Β§15 Step 23b.+ if (pref.pinned && !flags["yes"]) {+ process.stderr.write(+ `warning: preference '${pref.id}' is pinned; pass --yes to override\n`,+ );+ return 1;+ }++ const now = new Date();+ const todayDate = isoDate(now);+ const retiredBy = `[[Brain/log/${todayDate}]]`;++ try {+ moveToRetired(vault, path, "user-rejected", {+ now,+ retired_by: retiredBy,+ });+ } catch (exc) {+ return fail(`failed to retire preference: ${(exc as Error).message ?? exc}`);+ }++ // Log a `reject` event so the audit trail stays complete.+ try {+ const body: Record<string, string> = {+ preference: `[[ret-${slug}]]`,+ agent,+ };+ if (flags["reason"]) body["reason"] = String(flags["reason"]);+ if (pref.pinned) body["was_pinned"] = "true";+ appendLogEvent(vault, {+ timestamp: isoSecond(now),+ eventType: BRAIN_LOG_EVENT_KIND.reject,+ body,+ });+ } catch (err) {+ // Non-fatal: the retire move is already persisted; surface so the+ // gap in the audit trail is at least visible.+ process.stderr.write(+ `warning: append reject log failed: ${(err as Error).message}\n`,+ );+ }++ if (flags["json"]) {+ okJson({ id: `ret-${slug}`, reason: "user-rejected" });+ } else {+ ok(`retired: ret-${slug} (user-rejected)`);+ }+ return 0;+}++async function cmdBrainPin(argv: string[]): Promise<number> {+ return await pinOrUnpin(argv, true);+}++async function cmdBrainUnpin(argv: string[]): Promise<number> {+ return await pinOrUnpin(argv, false);+}++async function pinOrUnpin(argv: string[], value: boolean): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ id: { type: "string" },+ json: { type: "boolean" },+ });+ if (typeof flags["id"] !== "string" || (flags["id"] as string).trim() === "") {+ return fail(+ `brain ${value ? "pin" : "unpin"} missing required flag: --id`,+ );+ }+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);+ const agent = resolveAgentName(config);++ try {+ const out = setPinned(vault, String(flags["id"]), value, { agent });+ const slug = String(flags["id"]).trim().replace(/^pref-/, "");+ const label = value ? "pinned" : "unpinned";+ const idemLabel = value ? "already pinned" : "already unpinned";+ if (flags["json"]) {+ okJson({ id: `pref-${slug}`, changed: out.changed, pinned: value });+ } else if (out.changed) {+ ok(`${label}: pref-${slug}`);+ } else {+ ok(`${idemLabel}: pref-${slug}`);+ }+ return 0;+ } catch (exc) {+ if (exc instanceof BrainPreferenceNotFoundError) {+ process.stderr.write(`${exc.message}\n`);+ return 2;+ }+ return fail(+ `${value ? "pin" : "unpin"} failed: ${(exc as Error).message ?? exc}`,+ );+ }+}++async function cmdBrainRollback(argv: string[]): Promise<number> {+ const { flags, positional } = parse(argv, {+ vault: { type: "string" },+ list: { type: "boolean" },+ yes: { type: "boolean" },+ json: { type: "boolean" },+ });+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ // `--list` shows available snapshots in newest-first order, with size+ // for the operator's mental model. Idempotent and read-only.+ if (flags["list"]) {+ const snaps = listSnapshots(vault);+ if (flags["json"]) {+ process.stdout.write(JSON.stringify(snaps, null, 2) + "\n");+ return 0;+ }+ if (snaps.length === 0) {+ ok("no snapshots available");+ return 0;+ }+ ok("run_id\tcreated_at\tsize_bytes");+ for (const s of snaps) {+ ok(`${s.run_id}\t${s.created_at}\t${s.size_bytes}`);+ }+ return 0;+ }++ if (positional.length < 1) {+ return fail(+ "brain rollback requires a <run_id> argument (or --list to enumerate snapshots)",+ );+ }+ const runId = positional[0]!;++ // Quick existence probe so the user gets a useful exit-2 not-found+ // message instead of a deep error inside `restoreSnapshot`.+ const allSnaps = listSnapshots(vault);+ if (!allSnaps.some((s) => s.run_id === runId)) {+ process.stderr.write(+ `snapshot not found: ${runId}; run \`o2b brain rollback --list\` to enumerate.\n`,+ );+ return 2;+ }++ // Interactive confirm. We compute a minimal diff summary by counting+ // entries in the current state (the snapshot's content would require+ // extracting first; the headline is intentionally lightweight β "you+ // are about to overwrite N files").+ if (!flags["yes"]) {+ // Non-interactive guard: --json output or non-TTY stdin (CI, pipes)+ // would silently hang waiting for input. Fail fast and demand --yes+ // so automation never blocks on a dropped prompt.+ if (flags["json"] || !process.stdin.isTTY) {+ return fail(+ "rollback requires --yes in non-interactive mode (--json or non-TTY stdin)",+ );+ }+ const summary = diffSummary(vault);+ process.stderr.write(+ `About to restore snapshot '${runId}' over Brain/.\n` ++ `Current state: ${summary.preferences} preferences, ${summary.retired} retired, ${summary.signals} signals.\n` ++ `This will OVERWRITE the live Brain/ tree (.snapshots/ is preserved).\n` ++ `Proceed? [y/N] `,+ );+ const ans = await readSingleLine();+ if (ans.toLowerCase() !== "y" && ans.toLowerCase() !== "yes") {+ ok("rollback cancelled");+ return 0;+ }+ }++ let result;+ try {+ result = restoreSnapshot(vault, runId);+ } catch (exc) {+ return fail(`rollback failed: ${(exc as Error).message ?? exc}`);+ }++ // Log the rollback event so the audit trail shows the time-shift.+ try {+ appendLogEvent(vault, {+ timestamp: isoSecond(new Date()),+ eventType: BRAIN_LOG_EVENT_KIND.rollback,+ body: {+ run_id: runId,+ restored_files: String(result.restored_files),+ },+ });+ } catch (err) {+ // Non-fatal: the snapshot was already restored on disk; surface so+ // the gap in the audit trail is at least visible.+ process.stderr.write(+ `warning: append rollback log failed: ${(err as Error).message}\n`,+ );+ }++ if (flags["json"]) {+ okJson({ run_id: runId, restored_files: result.restored_files });+ } else {+ ok(`restored: ${runId} (${result.restored_files} files)`);+ }+ return 0;+}++async function cmdBrainDoctor(argv: string[]): Promise<number> {+ const { flags } = parse(argv, {+ vault: { type: "string" },+ strict: { type: "boolean" },+ json: { type: "boolean" },+ });+ const config = defaultConfigPath();+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);++ let result;+ try {+ result = runDoctor(vault, { strict: Boolean(flags["strict"]) });+ } catch (exc) {+ return fail(`doctor failed: ${(exc as Error).message ?? exc}`);+ }++ if (flags["json"]) {+ process.stdout.write(+ JSON.stringify(+ { warnings: result.warnings, errors: result.errors },+ null,+ 2,+ ) + "\n",+ );+ } else {+ for (const e of result.errors) {+ process.stdout.write(+ `[ERROR] ${e.code}: ${e.message}${e.path ? ` (${e.path})` : ""}\n`,+ );+ }+ for (const w of result.warnings) {+ process.stdout.write(+ `[WARN] ${w.code}: ${w.message}${w.path ? ` (${w.path})` : ""}\n`,+ );+ }+ if (result.errors.length === 0 && result.warnings.length === 0) {+ ok("brain doctor: clean");+ }+ }++ // Exit-code matrix per Β§9.2: errors β 1; warnings β 0 unless --strict+ // (then 2); clean β 0.+ if (result.errors.length > 0) return 1;+ if (result.warnings.length > 0 && flags["strict"]) return 2;+ return 0;+}++// ββ Help text βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++const BRAIN_HELP = `usage: o2b brain <verb> [args...]++Brain verbs (observing memory):+ init Bootstrap <vault>/Brain/ (idempotent; --force overwrites)+ feedback Record a taste signal (--topic, --signal, --principle)+ dream Run the deterministic dreaming pass (idempotent)+ apply-evidence Log a real-work application of a preference+ digest Render the recent-changes digest (markdown or --json)+ query Read by --preference, --topic, or --since+ reject Move a preference to retired (user-rejected); --yes if pinned+ pin Mark a preference exempt from automatic retire (idempotent)+ unpin Clear the pinned flag (idempotent)+ rollback Restore Brain/ from a snapshot (--list or <run_id>; --yes)+ doctor Validate Brain invariants (--strict promotes warnings to exit 2)++Common flags:+ --vault <path> Override the configured vault+ --json Structured output where applicable+ --help Per-verb help (run \`o2b brain <verb> --help\`)+`;++const VERB_HELP: Record<string, string> = {+ init:+ "usage: o2b brain init [--vault <path>] [--force] [--json]\n" ++ "Bootstrap <vault>/Brain/. Requires `o2b init` to have run first.\n",+ feedback:+ "usage: o2b brain feedback --topic <slug> --signal positive|negative --principle <text>\n" ++ " [--scope <slug>] [--source <wikilink>...] [--agent <name>] [--raw <text>|--raw-file <path>]\n" ++ " [--force-confirmed] [--vault <path>] [--json]\n" ++ "Creates a `sig-*.md` in Brain/inbox/. With --force-confirmed also creates a `pref-*.md`.\n",+ dream:+ "usage: o2b brain dream [--vault <path>] [--dry-run] [--now <ISO-8601>] [--json]\n" ++ "Runs the deterministic dreaming algorithm. Idempotent on rerun.\n",+ "apply-evidence":+ "usage: o2b brain apply-evidence --pref <id> --artifact <wikilink> --result applied|violated\n" ++ " [--agent <name>] [--note <text>] [--vault <path>] [--json]\n" ++ "Appends a single event to today's log. Missing preference exits 2.\n",+ digest:+ "usage: o2b brain digest [--vault <path>] [--since <ISO>] [--until <ISO>] [--json] [--silent-if-empty]\n" ++ "Renders the 24-hour change digest. Empty + --silent-if-empty exits 2.\n",+ query:+ "usage: o2b brain query --preference <id> | --topic <slug> | --since <ISO> [--vault <path>] [--json]\n" ++ "Read-only lookup. One of --preference / --topic / --since is required.\n",+ reject:+ "usage: o2b brain reject --id <pref-id> [--reason <text>] [--yes] [--vault <path>] [--json]\n" ++ "Move a preference to retired/ with reason 'user-rejected'. --yes required when pinned.\n",+ pin:+ "usage: o2b brain pin --id <pref-id> [--vault <path>] [--json]\n" ++ "Set pinned: true. Idempotent. Exempts the preference from automatic retire.\n",+ unpin:+ "usage: o2b brain unpin --id <pref-id> [--vault <path>] [--json]\n" ++ "Clear pinned: true. Idempotent.\n",+ rollback:+ "usage: o2b brain rollback <run_id> [--vault <path>] [--yes] [--json]\n" ++ " o2b brain rollback --list [--vault <path>] [--json]\n" ++ "Restore Brain/ from a snapshot. Interactive prompt unless --yes.\n",+ doctor:+ "usage: o2b brain doctor [--vault <path>] [--json] [--strict]\n" ++ "Validate invariants. Warnings exit 0 (or 2 with --strict). Errors always exit 1.\n",+};++// ββ Public entry point ββββββββββββββββββββββββββββββββββββββββββββββββββββββ++/**+ * Dispatch `o2b brain <verb> [...args]`. Returns the exit code; the caller+ * (`main.ts`) forwards it to `process.exit`. Unknown verbs print the+ * brain help text and return 2.+ */+export async function handleBrainSubcommand(+ argv: ReadonlyArray<string>,+): Promise<number> {+ if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {+ process.stdout.write(BRAIN_HELP);+ return argv.length === 0 ? 2 : 0;+ }+ const verb = argv[0]!;+ const rest = argv.slice(1);++ // Per-verb help.+ if (rest.length === 1 && (rest[0] === "-h" || rest[0] === "--help")) {+ const text = VERB_HELP[verb];+ if (text) {+ process.stdout.write(text);+ return 0;+ }+ // Unknown verb requesting --help: fall back to generic brain help+ // and return 2 (same exit code as the unknown-verb branch in the+ // dispatcher below).+ process.stdout.write(BRAIN_HELP);+ return 2;+ }++ try {+ switch (verb) {+ case "init":+ return await cmdBrainInit(rest);+ case "feedback":+ return await cmdBrainFeedback(rest);+ case "dream":+ return await cmdBrainDream(rest);+ case "apply-evidence":+ return await cmdBrainApplyEvidence(rest);+ case "digest":+ return await cmdBrainDigest(rest);+ case "query":+ return await cmdBrainQuery(rest);+ case "reject":+ return await cmdBrainReject(rest);+ case "pin":+ return await cmdBrainPin(rest);+ case "unpin":+ return await cmdBrainUnpin(rest);+ case "rollback":+ return await cmdBrainRollback(rest);+ case "doctor":+ return await cmdBrainDoctor(rest);+ default:+ process.stderr.write(`error: unknown brain verb: ${verb}\n`);+ process.stdout.write(BRAIN_HELP);+ return 2;+ }+ } catch (exc) {+ if (exc instanceof CliError) {+ process.stderr.write(`error: ${exc.message}\n`);+ return 1;+ }+ throw exc;+ }+}++// ββ Helpers βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++interface DiffSummary {+ readonly preferences: number;+ readonly retired: number;+ readonly signals: number;+}++/**+ * Count the entries currently under `Brain/{preferences,retired,inbox}/`.+ * Used for the interactive rollback confirmation so the operator sees+ * the scale of the overwrite before pressing `y`.+ */+function diffSummary(vault: string): DiffSummary {+ const root = resolve(vault, "Brain");+ const safeCount = (p: string): number => {+ if (!existsSync(p)) return 0;+ try {+ const st = statSync(p);+ if (!st.isDirectory()) return 0;+ } catch {+ return 0;+ }+ try {+ const entries: Dirent[] = readdirSync(p, { withFileTypes: true });+ return entries.filter((e) => e.isFile() && e.name.endsWith(".md")).length;+ } catch {+ return 0;+ }+ };+ return {+ preferences: safeCount(resolve(root, "preferences")),+ retired: safeCount(resolve(root, "retired")),+ signals: safeCount(resolve(root, "inbox")),+ };+}++/**+ * Read a single trimmed line from stdin. Returns `""` on EOF so the+ * default-N branch fires when the prompt receives no input (pipe closed,+ * non-interactive shell).+ */+function readSingleLine(): Promise<string> {+ return new Promise((res) => {+ let buf = "";+ const onData = (chunk: Buffer | string): void => {+ buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");+ const nl = buf.indexOf("\n");+ if (nl >= 0) {+ process.stdin.removeListener("data", onData);+ process.stdin.removeListener("end", onEnd);+ process.stdin.pause();+ res(buf.slice(0, nl).trim());+ }+ };+ const onEnd = (): void => {+ process.stdin.removeListener("data", onData);+ process.stdin.removeListener("end", onEnd);+ res(buf.trim());+ };+ process.stdin.resume();+ process.stdin.on("data", onData);+ process.stdin.on("end", onEnd);+ });+}++// ββ Renderers (text mode) βββββββββββββββββββββββββββββββββββββββββββββββββββ++function renderQueryPreferenceText(+ out: ReturnType<typeof queryByPreference>,+): void {+ const p = out.preference;+ ok(`id: ${p.id}`);+ ok(`topic: ${p.topic}`);+ if (p.scope) ok(`scope: ${p.scope}`);+ ok(`status: ${"status" in p ? p.status : "(unknown)"}`);+ ok(`principle: ${p.principle}`);+ if (out.evidence.length === 0) {+ ok("evidence: (none)");+ return;+ }+ ok("evidence:");+ for (const e of out.evidence) {+ const artifact = e.body["artifact"] ?? "(unknown)";+ const result = e.body["result"] ?? "(unknown)";+ info(` - ${e.timestamp} ${result}: ${artifact}`);+ }+}++function renderQueryTopicText(+ out: ReturnType<typeof queryByTopic>,+ topic: string,+): void {+ ok(`topic: ${topic}`);+ if (out.preference) {+ ok(`preference: ${out.preference.id}`);+ } else {+ ok("preference: (none)");+ }+ ok(`signals: ${out.signals.length}`);+ for (const s of out.signals) {+ info(` - ${s.id} (${s.signal}, ${s.created_at})`);+ }+ ok(`log_events: ${out.all_log_events.length}`);+}++function renderQueryLogText(entries: ReadonlyArray<BrainLogEntry>): void {+ ok(`entries: ${entries.length}`);+ for (const e of entries) {+ info(` - ${e.timestamp} ${e.eventType}`);+ }+}diff --git a/src/cli/main.ts b/src/cli/main.tsindex 312bd80e..386ce326 100644--- a/src/cli/main.ts+++ b/src/cli/main.ts@@ -43,6 +43,7 @@ import {import type { ReceiptPolicyStatus } from "../core/pay-memory/types.ts";import { listVaultPages, writeFrontmatter } from "../core/vault.ts";import { CliError, parseFlags } from "./argparse.ts";+import { handleBrainSubcommand } from "./brain.ts";import {installCli,renderInstallResult,@@ -1179,6 +1180,19 @@ Pay Memory:consume-payment-request Link an approved request to its resulting receiptlist-pending-payments List pending/approved/etc. requestspayment-digest Render a Telegram-friendly 4-line summary for a date (Hermes cron-friendly)++Brain (observing memory):+ brain init Bootstrap <vault>/Brain/ skeleton (idempotent)+ brain feedback Record a taste signal into Brain/inbox/+ brain dream Run the deterministic dreaming pass (idempotent)+ brain apply-evidence Log a real-work application of a preference+ brain digest Render the recent-changes digest (markdown or --json)+ brain query Read by --preference, --topic, or --since+ brain reject Move a preference to retired/ (user-rejected)+ brain pin Mark a preference exempt from automatic retire+ brain unpin Clear the pinned flag+ brain rollback Restore Brain/ from a snapshot (--list / <run_id>)+ brain doctor Validate Brain invariants (--strict promotes warnings)`;function sortedReplacer(_key: string, value: unknown): unknown {@@ -1197,7 +1211,9 @@ export async function main(argv: ReadonlyArray<string>): Promise<number> {const rest = argv.slice(1);// Per-command --help support: print the dedicated help line plus generic.- if (rest.length === 1 && (rest[0] === "-h" || rest[0] === "--help")) {+ // The `brain` subcommand has its own dispatcher with per-verb help, so we+ // skip the generic shortcut and hand control over directly.+ if (rest.length === 1 && (rest[0] === "-h" || rest[0] === "--help") && command !== "brain") {process.stdout.write(`${command}: see https://github.com/itechmeat/open-second-brain\n`);if (command === "uninstall") {process.stdout.write(@@ -1256,6 +1272,8 @@ export async function main(argv: ReadonlyArray<string>): Promise<number> {return await cmdListPendingPayments(rest);case "payment-digest":return await cmdPaymentDigest(rest);+ case "brain":+ return await handleBrainSubcommand(rest);default:process.stderr.write(`error: unknown command: ${command}\n`);process.stderr.write(HELP);diff --git a/src/core/brain/apply-evidence.ts b/src/core/brain/apply-evidence.tsnew file mode 100644index 00000000..a8dc8860--- /dev/null+++ b/src/core/brain/apply-evidence.ts@@ -0,0 +1,175 @@+/**+ * apply-evidence event appender.+ *+ * `apply-evidence` is the canonical durable signal that a preference was+ * exercised against real work. It is the only log event that drives the+ * `unconfirmed β confirmed` transition and the `applied_count` /+ * `violated_count` / `last_evidence_at` counters that `dream` recomputes+ * on every run.+ *+ * Surface:+ *+ * - {@link appendApplyEvidence} writes one apply-evidence entry to+ * `Brain/log/<today>.md`. The file is created on the first event of+ * the day; subsequent calls append. Returns the resolved log path+ * and the ISO timestamp used in the heading.+ *+ * - {@link BrainPreferenceNotFoundError} is the typed failure surface+ * for the "wrong pref_id" path. The CLI in Task 6 catches it and+ * exits with code 2 (informative, not error). We deliberately use a+ * distinct error class so callers can pattern-match on it without+ * a `.message.includes()` regex.+ *+ * The check on the preference is intentionally cheap: we resolve the+ * preference path under `Brain/preferences/<pref_id>.md` and verify it+ * exists + parses. We don't update the preference file from here β+ * `dream` is the only writer of preference frontmatter (counters,+ * confidence, status); `apply-evidence` only records the event. That+ * keeps the log as the single source of truth for evidence counts and+ * lets `dream` stay deterministic from the log alone.+ */++import { existsSync } from "node:fs";++import { appendLogEvent, type AppendLogEventResult, type BrainLogEntry } from "./log.ts";+import { parsePreference } from "./preference.ts";+import { preferencePath, validateSlug } from "./paths.ts";+import { isoSecond } from "./time.ts";+import {+ BRAIN_APPLY_RESULT,+ BRAIN_LOG_EVENT_KIND,+ type BrainApplyResult,+} from "./types.ts";++/**+ * Thrown by {@link appendApplyEvidence} when the targeted preference+ * does not exist on disk. The CLI surfaces this as exit code 2 (not an+ * error per se β the agent referenced an unknown rule and the operator+ * should learn about it without the run looking like a crash).+ */+export class BrainPreferenceNotFoundError extends Error {+ readonly prefId: string;+ readonly searchedPath: string;++ constructor(prefId: string, searchedPath: string) {+ super(+ `preference not found: ${prefId}; expected ${searchedPath}. ` ++ "Use `o2b brain query` to list active preferences.",+ );+ this.name = "BrainPreferenceNotFoundError";+ this.prefId = prefId;+ this.searchedPath = searchedPath;+ }+}++/** Input contract for {@link appendApplyEvidence}. */+export interface AppendApplyEvidenceInput {+ /**+ * Preference id, with or without the `pref-` prefix. Both+ * `pref-foo` and `foo` are accepted so the CLI and MCP layers can+ * be lenient about how callers spell the target.+ */+ readonly pref_id: string;+ /**+ * Wikilink target of the artifact where the rule was applied+ * (`[[Daily/2026.05.14#section]]`, `[[blog-header-draft]]`, β¦).+ * The string is recorded verbatim β we do not validate the link+ * resolves; the user's workflow chooses the convention.+ */+ readonly artifact: string;+ readonly result: BrainApplyResult;+ readonly agent: string;+ readonly note?: string;+}++export interface AppendApplyEvidenceOptions {+ /**+ * Override the wall clock. Defaults to `new Date()`. Tests pin this+ * so the resulting log entry is byte-deterministic.+ */+ readonly now?: Date;+}++export interface AppendApplyEvidenceResult {+ /** ISO-8601 UTC timestamp written to the log heading. */+ readonly logged_at: string;+ /** Absolute path of the log file the event landed in. */+ readonly log_path: string;+}++/**+ * Append one `apply-evidence` event to today's log. Throws+ * {@link BrainPreferenceNotFoundError} when the preference id does not+ * resolve to a file under `Brain/preferences/`.+ *+ * The log file is created on the first event of the day (the appender+ * inside `log.ts` handles that transparently). Subsequent calls on the+ * same UTC day append.+ */+export function appendApplyEvidence(+ vault: string,+ input: AppendApplyEvidenceInput,+ opts: AppendApplyEvidenceOptions = {},+): AppendApplyEvidenceResult {+ if (!input.pref_id || !input.pref_id.trim()) {+ throw new Error("apply-evidence missing field: pref_id");+ }+ if (!input.artifact || !input.artifact.trim()) {+ throw new Error("apply-evidence missing field: artifact");+ }+ if (!input.agent || !input.agent.trim()) {+ throw new Error("apply-evidence missing field: agent");+ }+ if (+ input.result !== BRAIN_APPLY_RESULT.applied &&+ input.result !== BRAIN_APPLY_RESULT.violated+ ) {+ throw new Error(+ `apply-evidence field 'result' must be 'applied' or 'violated'; got ${JSON.stringify(input.result)}`,+ );+ }++ // Resolve and validate the preference file. We accept both the bare+ // slug (`foo`) and the prefixed id (`pref-foo`) for caller comfort.+ const rawId = input.pref_id.trim();+ const slug = rawId.startsWith("pref-") ? rawId.slice("pref-".length) : rawId;+ if (!slug) {+ throw new Error(`apply-evidence: invalid pref_id (empty slug): ${input.pref_id}`);+ }+ validateSlug(slug);+ const prefFilePath = preferencePath(vault, slug);+ if (!existsSync(prefFilePath)) {+ throw new BrainPreferenceNotFoundError(`pref-${slug}`, prefFilePath);+ }+ // Parse so a corrupted target produces a meaningful error rather+ // than silently appending an evidence row that points at garbage.+ // Pollutes the typecheck only β we don't use the return value.+ parsePreference(prefFilePath);++ const now = opts.now ?? new Date();+ const timestamp = isoSecond(now);+ const wikilink = `[[pref-${slug}]]`;++ // Render the canonical payload. Ordering is deliberate: the wikilink+ // to the preference comes first so a human scrolling the log finds+ // the target rule immediately; the result follows so the reader sees+ // "what happened" before the optional note. Keys not present in the+ // input are omitted so the file stays as small as possible.+ const body: Record<string, string> = {+ preference: wikilink,+ artifact: input.artifact.trim(),+ agent: input.agent.trim(),+ result: input.result,+ };+ const note = input.note?.trim();+ if (note) body["note"] = note;++ const entry: BrainLogEntry = {+ timestamp,+ eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,+ body,+ };+ const result: AppendLogEventResult = appendLogEvent(vault, entry);+ return { logged_at: timestamp, log_path: result.logPath };+}+diff --git a/src/core/brain/digest.ts b/src/core/brain/digest.tsnew file mode 100644index 00000000..369b1cf7--- /dev/null+++ b/src/core/brain/digest.ts@@ -0,0 +1,602 @@+/**+ * Brain digest (design doc Β§8).+ *+ * Read-only renderer over Brain/log/ + Brain/preferences/ ++ * Brain/retired/. Default window: the last 24 hours, ending at+ * `opts.until ?? now`. Both Markdown and JSON outputs are supported;+ * the JSON form follows Β§8.2 verbatim so downstream consumers (Hermes+ * cron, CI scripts) can parse it without surprises.+ *+ * Sections, each rendered only when non-empty:+ *+ * 1. **New (unconfirmed, in trial)** β preferences with `status:+ * unconfirmed` and `created_at` inside the window.+ * 2. **Confirmed** β preferences with `confirmed_at` inside the+ * window.+ * 3. **Retired** β retired entries with `retired_at` inside the+ * window.+ * 4. **Confidence shifts** β preferences whose confidence changed+ * inside the window. The current Brain state does not carry an+ * explicit `confidence_history`; the design accepts a graceful+ * degradation here. We read `dream` log events: when their+ * payload exposes a `confidence_shifts` (singular bullet) or+ * `confidence_changes` sub-list, we parse those. If the payload+ * is absent, the section is empty.+ * 5. **Contradictions** β events of kind `contradicted` or `dream`+ * events emitting a `contradictions` sub-list. Same graceful+ * degradation: empty when the payload is not produced.+ *+ * Empty window β one-line Markdown `Brain digest β <date>: no changes`+ * (or JSON with `summary.empty: true`). The function returns both the+ * rendered string and an `empty` flag so the CLI can implement+ * `--silent-if-empty` (exit 2) without re-parsing.+ *+ * The function is pure read. It does not mutate signals, preferences,+ * retired entries, the log, or the snapshots.+ */++import { existsSync, readdirSync } from "node:fs";+import { join } from "node:path";++import { brainDirs, vaultRelative } from "./paths.ts";+import { normaliseWikilinkTarget } from "./wikilink.ts";+import { parsePreference, parseRetired } from "./preference.ts";+import { parseLogDay, type BrainLogEntry } from "./log.ts";+import {+ BRAIN_APPLY_RESULT,+ BRAIN_LOG_EVENT_KIND,+ BRAIN_RETIRED_REASON,+} from "./types.ts";+import type {+ BrainConfidence,+ BrainPreference,+ BrainRetired,+} from "./types.ts";++// ----- Public types ---------------------------------------------------------++export type DigestFormat = "markdown" | "json";++export interface RenderDigestOptions {+ /** Inclusive lower bound. Defaults to `until - 24h`. */+ readonly since?: Date;+ /** Exclusive upper bound. Defaults to `new Date()`. */+ readonly until?: Date;+ /** Output format. Defaults to `markdown`. */+ readonly format?: DigestFormat;+ /**+ * Injection seam for deterministic tests: defaults the generated_at+ * timestamp. Production callers do not pass this β the renderer+ * picks `new Date()` itself.+ */+ readonly now?: Date;+}++export interface RenderDigestResult {+ /** Rendered Markdown (default) or JSON body. */+ readonly content: string;+ /** True when every section is empty (single-line output / `summary.empty`). */+ readonly empty: boolean;+}++// ----- JSON shape (mirrors Β§8.2) -------------------------------------------++export interface DigestJsonNewUnconfirmed {+ readonly id: string;+ readonly topic: string;+ readonly scope: string | null;+ readonly signal_count: number;+ readonly unconfirmed_until: string;+ readonly path: string;+}++export interface DigestJsonConfirmed {+ readonly id: string;+ readonly topic: string;+ readonly scope: string | null;+ readonly confirmed_at: string;+ readonly first_applied_artifact: string | null;+}++export interface DigestJsonRetired {+ readonly id: string;+ readonly topic: string;+ readonly scope: string | null;+ readonly retired_at: string;+ readonly reason: string;+ readonly days_stale: number | null;+}++export interface DigestJsonConfidenceShift {+ readonly id: string;+ readonly from: BrainConfidence | string;+ readonly to: BrainConfidence | string;+ readonly applied_count: number | null;+ readonly violated_count: number | null;+}++export interface DigestJsonContradiction {+ readonly id: string;+ readonly topic: string | null;+ readonly description: string;+}++export interface DigestJson {+ readonly schema_version: 1;+ readonly generated_at: string;+ readonly window: { readonly since: string; readonly until: string };+ readonly summary: {+ readonly new_unconfirmed_count: number;+ readonly confirmed_count: number;+ readonly retired_count: number;+ readonly confidence_shift_count: number;+ readonly contradiction_count: number;+ readonly empty: boolean;+ };+ readonly new_unconfirmed: ReadonlyArray<DigestJsonNewUnconfirmed>;+ readonly confirmed: ReadonlyArray<DigestJsonConfirmed>;+ readonly retired: ReadonlyArray<DigestJsonRetired>;+ readonly confidence_shifts: ReadonlyArray<DigestJsonConfidenceShift>;+ readonly contradictions: ReadonlyArray<DigestJsonContradiction>;+}++// ----- Entry point ----------------------------------------------------------++const ONE_DAY_MS = 24 * 60 * 60 * 1000;++export function renderDigest(+ vault: string,+ opts: RenderDigestOptions = {},+): RenderDigestResult {+ const format = opts.format ?? "markdown";+ const now = opts.now ?? new Date();+ const until = opts.until ?? now;+ const since = opts.since ?? new Date(until.getTime() - ONE_DAY_MS);+ if (Number.isNaN(since.getTime()) || Number.isNaN(until.getTime())) {+ throw new TypeError("renderDigest: `since` and `until` must be valid Dates");+ }+ if (since.getTime() > until.getTime()) {+ throw new RangeError(+ `renderDigest: since (${since.toISOString()}) is after until (${until.toISOString()})`,+ );+ }++ const data = collectDigestData(vault, since, until);+ const empty = isEmpty(data);++ if (format === "json") {+ const payload: DigestJson = {+ schema_version: 1,+ generated_at: now.toISOString(),+ window: { since: since.toISOString(), until: until.toISOString() },+ summary: {+ new_unconfirmed_count: data.new_unconfirmed.length,+ confirmed_count: data.confirmed.length,+ retired_count: data.retired.length,+ confidence_shift_count: data.confidence_shifts.length,+ contradiction_count: data.contradictions.length,+ empty,+ },+ new_unconfirmed: data.new_unconfirmed,+ confirmed: data.confirmed,+ retired: data.retired,+ confidence_shifts: data.confidence_shifts,+ contradictions: data.contradictions,+ };+ return Object.freeze({+ content: JSON.stringify(payload, null, 2) + "\n",+ empty,+ });+ }++ // Markdown.+ const content = empty+ ? renderEmptyMarkdown(until)+ : renderMarkdown(data, since, until);+ return Object.freeze({ content, empty });+}++// ----- Data collection ------------------------------------------------------++interface DigestData {+ readonly new_unconfirmed: ReadonlyArray<DigestJsonNewUnconfirmed>;+ readonly confirmed: ReadonlyArray<DigestJsonConfirmed>;+ readonly retired: ReadonlyArray<DigestJsonRetired>;+ readonly confidence_shifts: ReadonlyArray<DigestJsonConfidenceShift>;+ readonly contradictions: ReadonlyArray<DigestJsonContradiction>;+}++function collectDigestData(+ vault: string,+ since: Date,+ until: Date,+): DigestData {+ const sinceMs = since.getTime();+ const untilMs = until.getTime();+ const inWindow = (iso: string | null): boolean => {+ if (!iso) return false;+ const t = Date.parse(iso);+ if (!Number.isFinite(t)) return false;+ return t >= sinceMs && t < untilMs;+ };++ // 1. Iterate preferences/ for unconfirmed (created_at in window) and+ // confirmed (confirmed_at in window).+ const preferences = readAllPreferences(vault);+ const new_unconfirmed: DigestJsonNewUnconfirmed[] = [];+ const confirmed: DigestJsonConfirmed[] = [];++ for (const { pref, path } of preferences) {+ if (pref.status === "unconfirmed" && inWindow(pref.created_at)) {+ new_unconfirmed.push({+ id: pref.id,+ topic: pref.topic,+ scope: pref.scope ?? null,+ signal_count: pref.evidenced_by.length,+ unconfirmed_until: pref.unconfirmed_until,+ path: vaultRelative(path, vault),+ });+ }+ if (pref.status === "confirmed" && inWindow(pref.confirmed_at)) {+ confirmed.push({+ id: pref.id,+ topic: pref.topic,+ scope: pref.scope ?? null,+ confirmed_at: pref.confirmed_at!,+ first_applied_artifact: findFirstAppliedArtifact(vault, pref.id),+ });+ }+ }++ // 2. Iterate retired/ for entries retired in window.+ const retiredEntries: DigestJsonRetired[] = [];+ for (const { ret, path } of readAllRetired(vault)) {+ void path;+ if (inWindow(ret.retired_at)) {+ const daysStale = daysStaleFor(ret);+ retiredEntries.push({+ id: ret.id,+ topic: ret.topic,+ scope: ret.scope ?? null,+ retired_at: ret.retired_at,+ reason: ret.retired_reason,+ days_stale: daysStale,+ });+ }+ }++ // 3 & 4. Confidence shifts and contradictions β degraded gracefully+ // when payload data is missing.+ const logEntries = readLogsInWindow(vault, since, until);+ const confidenceShifts = extractConfidenceShifts(logEntries);+ const contradictions = extractContradictions(logEntries);++ // Stable ordering β id ascending so two runs on the same fixture+ // produce byte-identical output.+ new_unconfirmed.sort((a, b) => a.id.localeCompare(b.id));+ confirmed.sort((a, b) => a.id.localeCompare(b.id));+ retiredEntries.sort((a, b) => a.id.localeCompare(b.id));++ return {+ new_unconfirmed,+ confirmed,+ retired: retiredEntries,+ confidence_shifts: confidenceShifts,+ contradictions,+ };+}++function isEmpty(data: DigestData): boolean {+ return (+ data.new_unconfirmed.length === 0 &&+ data.confirmed.length === 0 &&+ data.retired.length === 0 &&+ data.confidence_shifts.length === 0 &&+ data.contradictions.length === 0+ );+}++// ----- Filesystem scan helpers ---------------------------------------------++interface PreferenceWithPath {+ readonly pref: BrainPreference;+ readonly path: string;+}++function readAllPreferences(vault: string): ReadonlyArray<PreferenceWithPath> {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.preferences)) return [];+ const out: PreferenceWithPath[] = [];+ for (const entry of readdirSync(dirs.preferences, { withFileTypes: true })) {+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith("pref-")) continue;+ const path = join(dirs.preferences, entry.name);+ try {+ out.push({ pref: parsePreference(path), path });+ } catch {+ // The doctor reports corruption; digest skips silently.+ }+ }+ return out;+}++interface RetiredWithPath {+ readonly ret: BrainRetired;+ readonly path: string;+}++function readAllRetired(vault: string): ReadonlyArray<RetiredWithPath> {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.retired)) return [];+ const out: RetiredWithPath[] = [];+ for (const entry of readdirSync(dirs.retired, { withFileTypes: true })) {+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith("ret-")) continue;+ const path = join(dirs.retired, entry.name);+ try {+ out.push({ ret: parseRetired(path), path });+ } catch {+ // ditto+ }+ }+ return out;+}++function readLogsInWindow(+ vault: string,+ since: Date,+ until: Date,+): ReadonlyArray<BrainLogEntry> {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.log)) return [];+ const sinceIso = since.toISOString();+ const untilIso = until.toISOString();+ // Restrict scans to dates intersecting the window β but we err+ // permissive (one day before / after) to avoid TZ off-by-ones.+ const sinceDay = sinceIso.slice(0, 10);+ const untilDay = untilIso.slice(0, 10);+ const out: BrainLogEntry[] = [];+ const dates = readdirSync(dirs.log, { withFileTypes: true })+ .filter((d) => d.isFile() && d.name.endsWith(".md"))+ .map((d) => d.name.slice(0, -".md".length))+ .filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n))+ .sort();+ for (const date of dates) {+ if (date < addDays(sinceDay, -1)) continue;+ if (date > addDays(untilDay, 1)) continue;+ const { entries } = parseLogDay(vault, date);+ for (const e of entries) {+ if (e.timestamp >= sinceIso && e.timestamp < untilIso) {+ out.push(e);+ }+ }+ }+ out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));+ return out;+}++function addDays(day: string, delta: number): string {+ const t = Date.parse(`${day}T00:00:00Z`);+ if (!Number.isFinite(t)) return day;+ return new Date(t + delta * ONE_DAY_MS).toISOString().slice(0, 10);+}++/**+ * Best-effort lookup of the artifact wikilink for the first `applied`+ * apply-evidence event against a preference id. Returns null if no+ * applied evidence is found β e.g. a preference that was force-confirmed+ * without ever being applied. This matches design doc Β§8.2 example.+ */+function findFirstAppliedArtifact(+ vault: string,+ prefId: string,+): string | null {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.log)) return null;+ const dates = readdirSync(dirs.log, { withFileTypes: true })+ .filter((d) => d.isFile() && d.name.endsWith(".md"))+ .map((d) => d.name.slice(0, -".md".length))+ .filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n))+ .sort();+ for (const date of dates) {+ const { entries } = parseLogDay(vault, date);+ for (const e of entries) {+ if (e.eventType !== BRAIN_LOG_EVENT_KIND.applyEvidence) continue;+ if (e.body["result"] !== BRAIN_APPLY_RESULT.applied) continue;+ const prefPayload = e.body["preference"];+ if (typeof prefPayload === "string" && refersTo(prefPayload, prefId)) {+ const artifact = e.body["artifact"];+ if (typeof artifact === "string") return artifact;+ }+ }+ }+ return null;+}++function refersTo(payload: string, prefId: string): boolean {+ return normaliseWikilinkTarget(payload) === prefId;+}++function daysStaleFor(ret: BrainRetired): number | null {+ // For `stale-no-evidence`, the "days stale" is the gap between+ // `retired_at` and `last_evidence_at` (or `created_at` if there is+ // no evidence at all). Other reasons get null β the field is only+ // meaningful under stale-no-evidence per Β§8.2 example. We still+ // emit non-null for completeness on rebutted / expired-unconfirmed+ // when computable, but only for stale-no-evidence is it the canonical+ // metric the digest's "(91 days)" parenthetical refers to.+ if (ret.retired_reason !== BRAIN_RETIRED_REASON.staleNoEvidence) return null;+ const start = ret.last_evidence_at ?? ret.created_at;+ const startMs = Date.parse(start);+ const endMs = Date.parse(ret.retired_at);+ if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;+ return Math.max(0, Math.floor((endMs - startMs) / ONE_DAY_MS));+}++// ----- Confidence shifts & contradictions ----------------------------------+//+// Task 3 (`dream.ts`) is in progress as we ship this. It is the only+// component that can authoritatively emit confidence transitions and+// contradictions; without its payload data we cannot reconstruct+// transitions from filesystem state alone (the current `confidence`+// field has no `from` value to compare against). Per the Β§15 Task 4+// spec, the digest tolerates the absent payload as a graceful empty.+//+// When dream eventually emits these in its run summary, the parsers+// below will pick them up because we look in flexible payload shapes+// (the `dream` event's bullet list).++function extractConfidenceShifts(+ entries: ReadonlyArray<BrainLogEntry>,+): ReadonlyArray<DigestJsonConfidenceShift> {+ const out: DigestJsonConfidenceShift[] = [];+ for (const e of entries) {+ if (e.eventType !== BRAIN_LOG_EVENT_KIND.dream) continue;+ // Pattern A: a `confidence_shifts` array, each item like+ // `[[pref-foo]] medium -> high (applied: 11, violated: 0)`.+ const shifts = e.body["confidence_shifts"];+ if (Array.isArray(shifts)) {+ for (const raw of shifts) {+ const parsed = parseShiftLine(raw);+ if (parsed) out.push(parsed);+ }+ }+ }+ return out;+}++function parseShiftLine(raw: string): DigestJsonConfidenceShift | null {+ // Tolerant parser: accept `[[pref-x]] medium -> high (applied: N, violated: M)`+ // and variations (en-dash / em-dash for arrow, missing parens).+ const m = /^\s*(?:\[\[([^\]]+)\]\]|(\S+))\s+(\w+)\s*(?:->|β)\s*(\w+)(?:\s*\(([^)]*)\))?/.exec(+ raw,+ );+ if (!m) return null;+ const idRaw = (m[1] ?? m[2])!.split(/[|#]/)[0]!.trim();+ if (!idRaw) return null;+ const from = m[3]!;+ const to = m[4]!;+ let applied: number | null = null;+ let violated: number | null = null;+ if (m[5]) {+ const appMatch = /applied\s*[:=]?\s*(\d+)/i.exec(m[5]);+ if (appMatch) applied = parseInt(appMatch[1]!, 10);+ const violMatch = /violated\s*[:=]?\s*(\d+)/i.exec(m[5]);+ if (violMatch) violated = parseInt(violMatch[1]!, 10);+ }+ return { id: idRaw, from, to, applied_count: applied, violated_count: violated };+}++function extractContradictions(+ entries: ReadonlyArray<BrainLogEntry>,+): ReadonlyArray<DigestJsonContradiction> {+ const out: DigestJsonContradiction[] = [];+ for (const e of entries) {+ if (e.eventType !== BRAIN_LOG_EVENT_KIND.dream) continue;+ const list = e.body["contradictions"];+ if (Array.isArray(list)) {+ for (const raw of list) {+ const parsed = parseContradictionLine(raw);+ if (parsed) out.push(parsed);+ }+ }+ }+ return out;+}++function parseContradictionLine(raw: string): DigestJsonContradiction | null {+ // Best-effort: extract a wikilink as id and treat the rest as topic+ // or description. A missing wikilink means we cannot anchor the+ // contradiction to a preference; skip rather than fabricate.+ const wm = /\[\[([^\]]+)\]\]/.exec(raw);+ if (!wm) return null;+ const id = wm[1]!.split(/[|#]/)[0]!.trim();+ const description = raw.replace(wm[0], "").trim() || raw.trim();+ // The line may carry `(topic: foo)` β pull it out if present.+ let topic: string | null = null;+ const tm = /topic\s*[:=]\s*([A-Za-z0-9_-]+)/.exec(description);+ if (tm) topic = tm[1]!;+ return { id, topic, description };+}++// ----- Markdown rendering --------------------------------------------------++function renderEmptyMarkdown(until: Date): string {+ // Single-line collapse per Β§8 paragraph above the listing.+ const ymd = until.toISOString().slice(0, 10);+ return `Brain digest β ${ymd}: no changes\n`;+}++function renderMarkdown(+ data: DigestData,+ since: Date,+ until: Date,+): string {+ const sinceIso = since.toISOString();+ const untilIso = until.toISOString();+ const windowHours = Math.round(+ (until.getTime() - since.getTime()) / (60 * 60 * 1000),+ );+ const lines: string[] = [];+ lines.push(+ `# Brain digest β ${untilIso.slice(0, 16)}Z (${windowHours}h)`,+ "",+ `Window: ${sinceIso} β ${untilIso}`,+ "",+ );++ if (data.new_unconfirmed.length > 0) {+ lines.push("## New (unconfirmed, in trial)", "");+ for (const item of data.new_unconfirmed) {+ const scope = item.scope ?? "β";+ const trialDay = item.unconfirmed_until.slice(0, 10);+ lines.push(+ `- [[${item.id}]] β ${scope}, ${item.signal_count} signals, trial ends ${trialDay}`,+ );+ }+ lines.push("");+ }+ if (data.confirmed.length > 0) {+ lines.push("## Confirmed", "");+ for (const item of data.confirmed) {+ const scope = item.scope ?? "β";+ const artifact = item.first_applied_artifact ?? "_(none)_";+ lines.push(`- [[${item.id}]] β ${scope}, first applied in ${artifact}`);+ }+ lines.push("");+ }+ if (data.retired.length > 0) {+ lines.push("## Retired", "");+ for (const item of data.retired) {+ const scope = item.scope ?? "β";+ const detail =+ item.reason === BRAIN_RETIRED_REASON.staleNoEvidence && item.days_stale !== null+ ? `${item.reason} (${item.days_stale} days)`+ : item.reason;+ lines.push(`- [[${item.id}]] β ${scope}, ${detail}`);+ }+ lines.push("");+ }+ if (data.confidence_shifts.length > 0) {+ lines.push("## Confidence shifts", "");+ for (const item of data.confidence_shifts) {+ const stats =+ item.applied_count !== null && item.violated_count !== null+ ? ` (applied: ${item.applied_count}, violated: ${item.violated_count})`+ : "";+ lines.push(`- [[${item.id}]] ${item.from} β ${item.to}${stats}`);+ }+ lines.push("");+ }+ if (data.contradictions.length > 0) {+ lines.push("## Contradictions", "");+ for (const item of data.contradictions) {+ const topic = item.topic ? ` (topic: ${item.topic})` : "";+ lines.push(`- [[${item.id}]] β ${item.description}${topic}`);+ }+ lines.push("");+ }++ return lines.join("\n").replace(/\n+$/, "\n");+}+diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.tsnew file mode 100644index 00000000..8e564725--- /dev/null+++ b/src/core/brain/doctor.ts@@ -0,0 +1,520 @@+/**+ * Brain layer invariant checker (design doc Β§13.5).+ *+ * Pure read. Walks `<vault>/Brain/` and reports a list of issues. The+ * caller decides the exit code: warnings are non-blocking, errors+ * indicate a corrupt state. The CLI (`o2b brain doctor [--strict]`)+ * wraps the result; this module ships the structured object.+ *+ * Invariants checked:+ *+ * 1. **Schema version.** `Brain/_brain.yaml schema_version` is known+ * to this build. Unknown β error.+ * 2. **Required fields per kind.** Signal / preference / retired+ * frontmatter parses through the Task 2 parsers, which throw on+ * missing required fields. We re-wrap the throw as an error issue.+ * 3. **Status-vs-folder.** A file in `preferences/` whose status is+ * not `unconfirmed` / `confirmed` is a warning; a file in+ * `retired/` whose status is not `retired` is a warning.+ * `BrainStatusFolderMismatchError` from the parsers feeds this.+ * 4. **Broken wikilinks.** Every `[[basename]]` referenced by+ * `evidenced_by`, `supersedes`, `superseded_by`, or `retired_by`+ * on any Brain artifact must resolve to an existing Markdown file+ * somewhere inside `Brain/` (basename match, Obsidian-style).+ * Unresolved β warning.+ * 5. **Duplicate id.** Two distinct files whose frontmatter `id` is+ * identical β error.+ * 6. **Invalid ISO.** `created_at`, `unconfirmed_until`,+ * `confirmed_at`, `last_evidence_at`, `retired_at` parse as+ * ISO-8601 timestamps (`null` / missing acceptable for the+ * optional ones). Bad β error.+ * 7. **Log header parsing.** Every malformed `## <HH:MM:SS>Z β kind`+ * block surfaced by `parseLogDay` as a warning is forwarded here.+ *+ * The function never mutates state. It will gracefully tolerate a+ * vault that has no Brain layer yet (returns clean) β same shape as+ * the existing `doctor` legacy command on an empty vault.+ */++import { existsSync, readdirSync } from "node:fs";+import { basename, join } from "node:path";++import { extractWikilinks, parseFrontmatter } from "../vault.ts";+import {+ BRAIN_CONFIG_SUPPORTED_VERSIONS,+ BrainConfigError,+ loadBrainConfigDetailed,+} from "./policy.ts";+import { brainConfigPath, brainDirs } from "./paths.ts";+import { parseLogDay } from "./log.ts";+import {+ BrainStatusFolderMismatchError,+ parsePreference,+ parseRetired,+} from "./preference.ts";+import { parseSignal } from "./signal.ts";+import { normaliseWikilinkTarget } from "./wikilink.ts";++// ----- Public types ---------------------------------------------------------++export type DoctorSeverity = "warning" | "error";++/**+ * One structured finding. `code` is a stable identifier so callers can+ * filter or aggregate without parsing the `message`.+ */+export interface DoctorIssue {+ readonly severity: DoctorSeverity;+ readonly code: string;+ /** Vault-absolute path of the offending file, when known. */+ readonly path?: string;+ /** Human-readable description, suitable for `--text` rendering. */+ readonly message: string;+}++export interface RunDoctorOptions {+ /**+ * Reserved for future per-check toggles. Today the doctor reports+ * every check it knows; CLI `--strict` only changes the exit code,+ * not the contents of the report.+ */+ readonly strict?: boolean;+}++export interface RunDoctorResult {+ readonly warnings: ReadonlyArray<DoctorIssue>;+ readonly errors: ReadonlyArray<DoctorIssue>;+}++// ----- Entry point ----------------------------------------------------------++export function runDoctor(+ vault: string,+ opts: RunDoctorOptions = {},+): RunDoctorResult {+ void opts; // `strict` is a CLI exit-code concern, not a content one.++ const issues: DoctorIssue[] = [];++ const dirs = brainDirs(vault);+ if (!existsSync(dirs.brain)) {+ // No Brain layer present is not an error here β `o2b brain init`+ // is the right command, but a vault without Brain is allowed in+ // v0.9. Return clean.+ return Object.freeze({+ warnings: Object.freeze([]),+ errors: Object.freeze([]),+ });+ }++ // 1. Config schema check.+ checkConfig(vault, issues);++ // 2-6. Frontmatter checks across signals / preferences / retired.+ const knownBasenames = collectAllBasenames(vault);+ const idIndex = new Map<string, string[]>();++ checkSignals(vault, issues, idIndex);+ checkPreferences(vault, issues, idIndex, knownBasenames);+ checkRetired(vault, issues, idIndex, knownBasenames);++ // Duplicate-id reporting after every file has been indexed.+ for (const [id, paths] of idIndex.entries()) {+ if (paths.length > 1) {+ issues.push({+ severity: "error",+ code: "duplicate-id",+ message: `duplicate id '${id}' across files: ${paths.join(", ")}`,+ });+ }+ }++ // 7. Log header parsing β surface warnings from `parseLogDay`.+ checkLogs(vault, issues);++ // Partition by severity. Stable sort preserves discovery order which+ // is convenient for tests asserting on `path`+`code`.+ const warnings = issues.filter((i) => i.severity === "warning");+ const errors = issues.filter((i) => i.severity === "error");++ return Object.freeze({+ warnings: Object.freeze(warnings),+ errors: Object.freeze(errors),+ });+}++// ----- Config check ---------------------------------------------------------++function checkConfig(vault: string, issues: DoctorIssue[]): void {+ const cfgPath = brainConfigPath(vault);+ if (!existsSync(cfgPath)) {+ issues.push({+ severity: "error",+ code: "config-missing",+ path: cfgPath,+ message:+ "_brain.yaml is missing; run `o2b brain init` to bootstrap the Brain layer",+ });+ return;+ }+ try {+ const { config, warnings } = loadBrainConfigDetailed(vault);+ if (!BRAIN_CONFIG_SUPPORTED_VERSIONS.includes(config.schema_version)) {+ issues.push({+ severity: "error",+ code: "schema-version-unknown",+ path: cfgPath,+ message:+ `_brain.yaml schema_version ${config.schema_version} is not in the supported set ` ++ `(${BRAIN_CONFIG_SUPPORTED_VERSIONS.join(", ")})`,+ });+ }+ for (const w of warnings) {+ issues.push({+ severity: "warning",+ code: "config-warning",+ path: cfgPath,+ message: w.message,+ });+ }+ } catch (err) {+ if (err instanceof BrainConfigError) {+ issues.push({+ severity: "error",+ code: "config-invalid",+ path: cfgPath,+ message: err.message,+ });+ } else {+ issues.push({+ severity: "error",+ code: "config-invalid",+ path: cfgPath,+ message: `_brain.yaml could not be loaded: ${(err as Error).message ?? String(err)}`,+ });+ }+ }+}++// ----- Signal check ---------------------------------------------------------++function checkSignals(+ vault: string,+ issues: DoctorIssue[],+ idIndex: Map<string, string[]>,+): void {+ const dirs = brainDirs(vault);+ for (const dir of [dirs.inbox, dirs.processed]) {+ if (!existsSync(dir)) continue;+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ if (!entry.isFile()) continue;+ if (!entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith("sig-")) continue;+ const path = join(dir, entry.name);+ try {+ const sig = parseSignal(path);+ registerId(idIndex, sig.id, path);+ checkIso(path, "created_at", sig.created_at, issues);+ const expectedId = entry.name.slice(0, -".md".length);+ if (sig.id !== expectedId) {+ issues.push({+ severity: "warning",+ code: "id-filename-mismatch",+ path,+ message: `signal id '${sig.id}' differs from filename basename '${expectedId}'`,+ });+ }+ } catch (err) {+ issues.push({+ severity: "error",+ code: "signal-invalid",+ path,+ message: (err as Error).message ?? String(err),+ });+ }+ }+ }+}++// ----- Preference check -----------------------------------------------------++function checkPreferences(+ vault: string,+ issues: DoctorIssue[],+ idIndex: Map<string, string[]>,+ knownBasenames: ReadonlySet<string>,+): void {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.preferences)) return;+ for (const entry of readdirSync(dirs.preferences, { withFileTypes: true })) {+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith("pref-")) continue;+ const path = join(dirs.preferences, entry.name);+ try {+ const pref = parsePreference(path);+ registerId(idIndex, pref.id, path);+ checkIso(path, "created_at", pref.created_at, issues);+ checkIso(path, "unconfirmed_until", pref.unconfirmed_until, issues);+ if (pref.confirmed_at !== null) {+ checkIso(path, "confirmed_at", pref.confirmed_at, issues);+ }+ if (pref.last_evidence_at !== null) {+ checkIso(path, "last_evidence_at", pref.last_evidence_at, issues);+ }+ // Status invariant β the parser already enforces the canonical+ // values via the enum; a non-canonical value would have thrown+ // BrainStatusFolderMismatchError, caught below. Reaching here+ // means the status is valid; nothing more to check.+ checkWikilinks(+ path,+ "evidenced_by",+ pref.evidenced_by,+ knownBasenames,+ issues,+ );+ if (pref.supersedes) {+ checkWikilinks(+ path,+ "supersedes",+ [pref.supersedes],+ knownBasenames,+ issues,+ );+ }+ } catch (err) {+ if (err instanceof BrainStatusFolderMismatchError) {+ issues.push({+ severity: "warning",+ code: "status-folder-mismatch",+ path,+ message: err.message,+ });+ } else {+ // Distinguish field-missing errors (write-time contract) from+ // unexpected throws so the CLI report stays useful.+ const msg = (err as Error).message ?? String(err);+ const isMissingField = /missing field/.test(msg);+ const isInvalidIso = /ISO-8601/i.test(msg);+ issues.push({+ severity: "error",+ code: isMissingField+ ? "preference-missing-field"+ : isInvalidIso+ ? "iso-invalid"+ : "preference-invalid",+ path,+ message: msg,+ });+ }+ }+ }+}++// ----- Retired check --------------------------------------------------------++function checkRetired(+ vault: string,+ issues: DoctorIssue[],+ idIndex: Map<string, string[]>,+ knownBasenames: ReadonlySet<string>,+): void {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.retired)) return;+ for (const entry of readdirSync(dirs.retired, { withFileTypes: true })) {+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;+ if (!entry.name.startsWith("ret-")) continue;+ const path = join(dirs.retired, entry.name);+ try {+ const ret = parseRetired(path);+ registerId(idIndex, ret.id, path);+ checkIso(path, "created_at", ret.created_at, issues);+ checkIso(path, "retired_at", ret.retired_at, issues);+ if (ret.last_evidence_at !== null) {+ checkIso(path, "last_evidence_at", ret.last_evidence_at, issues);+ }+ checkWikilinks(+ path,+ "evidenced_by",+ ret.evidenced_by,+ knownBasenames,+ issues,+ );+ checkWikilinks(+ path,+ "retired_by",+ [ret.retired_by],+ knownBasenames,+ issues,+ );+ if (ret.superseded_by) {+ checkWikilinks(+ path,+ "superseded_by",+ [ret.superseded_by],+ knownBasenames,+ issues,+ );+ }+ } catch (err) {+ if (err instanceof BrainStatusFolderMismatchError) {+ issues.push({+ severity: "warning",+ code: "status-folder-mismatch",+ path,+ message: err.message,+ });+ } else {+ const msg = (err as Error).message ?? String(err);+ const isMissingField = /missing field/.test(msg);+ const isInvalidIso = /ISO-8601/i.test(msg);+ issues.push({+ severity: "error",+ code: isMissingField+ ? "retired-missing-field"+ : isInvalidIso+ ? "iso-invalid"+ : "retired-invalid",+ path,+ message: msg,+ });+ }+ }+ }+}++// ----- Log check ------------------------------------------------------------++function checkLogs(vault: string, issues: DoctorIssue[]): void {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.log)) return;+ const dates = readdirSync(dirs.log, { withFileTypes: true })+ .filter((d) => d.isFile() && d.name.endsWith(".md"))+ .map((d) => d.name.slice(0, -".md".length))+ .filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n));+ for (const date of dates) {+ const { warnings } = parseLogDay(vault, date);+ for (const w of warnings) {+ issues.push({+ severity: "warning",+ code: "log-malformed",+ path: w.path,+ message: `line ${w.lineNumber}: ${w.message}`,+ });+ }+ }+}++// ----- Helpers --------------------------------------------------------------++function registerId(+ idIndex: Map<string, string[]>,+ id: string,+ path: string,+): void {+ const list = idIndex.get(id);+ if (list) list.push(path);+ else idIndex.set(id, [path]);+}++// ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.fff)?Z. Lenient β we accept the+// shorter date-only form too (created_at is sometimes a date-only string+// in hand-authored signals).+const ISO_RE =+ /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)?$/;++function checkIso(+ path: string,+ field: string,+ value: string,+ issues: DoctorIssue[],+): void {+ if (!ISO_RE.test(value)) {+ issues.push({+ severity: "error",+ code: "iso-invalid",+ path,+ message: `field '${field}' is not a valid ISO-8601 timestamp: ${JSON.stringify(value)}`,+ });+ return;+ }+ // Confirm the calendar date is real (Date.parse accepts garbage on+ // some engines β but verifying via Date round-trip catches it).+ const ts = Date.parse(value);+ if (!Number.isFinite(ts)) {+ issues.push({+ severity: "error",+ code: "iso-invalid",+ path,+ message: `field '${field}' could not be parsed as a date: ${JSON.stringify(value)}`,+ });+ }+}++function checkWikilinks(+ path: string,+ field: string,+ values: ReadonlyArray<string>,+ knownBasenames: ReadonlySet<string>,+ issues: DoctorIssue[],+): void {+ for (const raw of values) {+ if (!raw) continue;+ // Extract any wikilinks via the shared parser. A bare `[[target]]`+ // produces one match; an already-stripped basename produces zero,+ // in which case we treat the raw string itself as the candidate.+ const matches = extractWikilinks(raw);+ const candidates = matches.length > 0 ? matches : [raw];+ for (const candidate of candidates) {+ const target = normaliseWikilinkTarget(candidate);+ if (!target) continue;+ if (!knownBasenames.has(target)) {+ issues.push({+ severity: "warning",+ code: "broken-wikilink",+ path,+ message: `field '${field}' references missing basename '${target}'`,+ });+ }+ }+ }+}++/**+ * Build the universe of valid wikilink targets inside `Brain/`. We+ * deliberately do NOT pull in legacy `AI Wiki/` or `Daily/` notes β a+ * Brain artifact pointing at a Daily entry (artifact wikilink in a+ * `apply-evidence` event) is valid, but those targets sit outside the+ * Brain layer and are out of scope for this doctor pass.+ *+ * To keep the check honest for cross-layer wikilinks (e.g. a+ * `retired_by: [[Brain/log/2026-05-14]]`), we accept *any* `.md` file+ * inside `Brain/`. The set is keyed by basename (without `.md`) so+ * Obsidian's basename match works.+ */+function collectAllBasenames(vault: string): ReadonlySet<string> {+ const out = new Set<string>();+ const dirs = brainDirs(vault);+ for (const d of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ ]) {+ if (!existsSync(d)) continue;+ for (const entry of readdirSync(d, { withFileTypes: true })) {+ if (!entry.isFile()) continue;+ if (!entry.name.endsWith(".md")) continue;+ out.add(entry.name.slice(0, -".md".length));+ }+ }+ return out;+}++// Force a runtime touch of parseFrontmatter so importers don't strip+// the dependency on the shared frontmatter parser β used implicitly by+// the parsers we delegate to. Kept here for clarity that doctor's+// invariants ultimately bottom out in the same parse pipeline as the+// dream loop.+void parseFrontmatter;diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.tsnew file mode 100644index 00000000..2f6f7bee--- /dev/null+++ b/src/core/brain/dream.ts@@ -0,0 +1,1162 @@+/**+ * `dream` β the only mutating batch operation in the Brain layer.+ *+ * `dream` reads the current Brain state and decides which transitions+ * to apply. It is deterministic given the inputs and the configured+ * time (the `--now` parameter). The algorithm is anchored in design+ * doc Β§7.3 and the per-rule clarifications in Β§7.4.+ *+ * Outputs (high level):+ *+ * - Pre-run snapshot under `Brain/.snapshots/<run_id>.tar.zst`,+ * created BEFORE any state-changing write so a crash mid-run can+ * be rolled back atomically.+ * - New / updated files in `Brain/preferences/`.+ * - Moves into `Brain/retired/`.+ * - Moves from `Brain/inbox/` into `Brain/inbox/processed/`.+ * - One appended event in `Brain/log/<today>.md` summarising the+ * run β **only** if any state actually changed. Idempotent reruns+ * touch nothing.+ *+ * Invariants:+ *+ * - Same-sign signals on an active preference are noted (moved to+ * `processed/`, log event `noted-redundant`) but do NOT create a+ * second preference and do NOT increment `applied_count`.+ * - Opposite-sign signals against an active preference accumulate+ * toward a rebuttal. Hitting `candidate_threshold` retires the+ * active preference (reason `rebutted`) UNLESS it is pinned, in+ * which case the rebut attempt is logged as a `retain-pinned`+ * event and the preference stays.+ * - Corrupted frontmatter on a single file produces a+ * `skip-corrupted-frontmatter` log event and is skipped. The run+ * continues for the rest of the tree.+ * - dryRun mode returns the planned summary but performs no writes.+ */++import { existsSync, readdirSync, renameSync } from "node:fs";+import { basename, join } from "node:path";++import { parseFrontmatter } from "../vault.ts";+import {+ appendLogEvent,+ parseLogDay,+ type BrainLogEntry,+} from "./log.ts";+import {+ moveToRetired,+ parsePreference,+ writePreference,+} from "./preference.ts";+import { parseSignal } from "./signal.ts";+import { isPinned } from "./pin.ts";+import {+ createSnapshot,+ pruneSnapshots,+} from "./snapshot.ts";+import { loadBrainConfig } from "./policy.ts";+import {+ brainDirs,+ preferencePath,+ processedSignalPath,+ retiredPath,+ vaultRelative,+} from "./paths.ts";+import { isoDate, isoSecond } from "./time.ts";+import { parseWikilink } from "./wikilink.ts";+import {+ BRAIN_APPLY_RESULT,+ BRAIN_CONFIDENCE,+ BRAIN_LOG_EVENT_KIND,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_RETIRED_REASON,+ BRAIN_SIGNAL_SIGN,+ type BrainConfidence,+ type BrainConfig,+ type BrainPreference,+ type BrainRetiredReason,+ type BrainSignal,+ type BrainSignalSign,+} from "./types.ts";++// ----- Public types --------------------------------------------------------++export interface DreamRunSummary {+ /** `dream-YYYY-MM-DD-HHMMSS`. */+ readonly run_id: string;+ /** False on a true no-op run (no signals, no transitions, no retires). */+ readonly changed: boolean;+ /** Preference ids newly created in `unconfirmed` state. */+ readonly new_unconfirmed: ReadonlyArray<string>;+ /** Preference ids transitioning `unconfirmed β confirmed`. */+ readonly confirmed: ReadonlyArray<string>;+ /** Preferences moved to `retired/` and the reason for each. */+ readonly retired: ReadonlyArray<{ id: string; reason: BrainRetiredReason }>;+ /** Topic slugs where opposite-sign signals are accumulating but no+ * state change happened yet (window not exceeded, or pinned). */+ readonly contradictions: ReadonlyArray<string>;+ /** Signal ids moved from inbox/ into inbox/processed/. */+ readonly moved_to_processed: ReadonlyArray<string>;+ /** 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). */+ readonly log_path?: string;+ /** True iff the run was a dry-run (no on-disk mutations performed). */+ readonly dry_run?: boolean;+}++export interface DreamOptions {+ /** Wall clock for the run. Defaults to `new Date()`. */+ readonly now?: Date;+ /** When true, compute the plan but make no writes. */+ readonly dryRun?: boolean;+}++// ----- Internal scan types ------------------------------------------------++interface SignalRecord {+ readonly path: string;+ readonly signal: BrainSignal;+ /** True iff the file lives in `inbox/` (not `processed/`). */+ readonly active: boolean;+}++interface PreferenceRecord {+ readonly path: string;+ readonly pref: BrainPreference;+}++interface RetiredRecord {+ readonly path: string;+ readonly topic: string;+ readonly id: string;+}++interface CorruptedEntry {+ readonly path: string;+}++interface ScanResult {+ readonly signals: SignalRecord[];+ readonly preferences: PreferenceRecord[];+ readonly retired: RetiredRecord[];+ readonly corrupted: CorruptedEntry[];+}++// ----- Main entry ----------------------------------------------------------++export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {+ const now = opts.now ?? new Date();+ const dryRun = opts.dryRun === true;+ const cfg = loadBrainConfig(vault);+ const runId = formatRunId(now);+ const wikilinkToRun = `[[Brain/log/${isoDate(now)}]]`;++ // 0. Scan the whole Brain/ tree. Corrupted files (frontmatter+ // parse-errors) are surfaced separately so the planning phase+ // can emit `skip-corrupted-frontmatter` log entries without+ // aborting.+ const scan = scanBrain(vault);++ // 1-2. Plan per-topic transitions: new unconfirmed preferences,+ // same-sign noted-redundant moves, rebuttal accumulation.+ const plan = planTopics(scan, cfg, now, wikilinkToRun);++ // 3. Plan refresh: applied / violated / last_evidence / confidence,+ // and unconfirmed β confirmed promotion. We need the log of all+ // apply-evidence entries up to `now` β we read every day file+ // referenced by `last_evidence_at` plus today's file. Since the+ // plan doesn't yet know dates, we scan the entire log/ directory.+ const evidence = scanApplyEvidence(vault);+ const refresh = planRefresh(scan, evidence, cfg, now, plan);++ // 4. Plan retires (expired-unconfirmed, stale-no-evidence). Pinned+ // preferences get a `retain-pinned` log event instead of a real+ // retire.+ planAutoRetires(scan, cfg, now, plan, refresh);++ // 5. Plan signal moves (inbox/ β processed/).+ planSignalMoves(scan, plan);++ // Decide if anything is going to change. We treat any of the+ // following as a state change:+ // - a new unconfirmed pref+ // - a refreshed pref (counters/confidence/status changed)+ // - a retire+ // - a same-sign signal noted on an active pref (move + log)+ // - a corrupted frontmatter (we want the skip event recorded)+ // - any pinned-rebut-attempt warning+ const changed =+ plan.newUnconfirmed.length > 0 ||+ refresh.confirmed.size > 0 ||+ refresh.updated.size > 0 ||+ plan.retires.length > 0 ||+ plan.notedRedundant.length > 0 ||+ plan.signalsToMove.size > 0 ||+ plan.retainPinned.length > 0 ||+ scan.corrupted.length > 0;++ if (!changed) {+ return Object.freeze({+ run_id: runId,+ changed: false,+ new_unconfirmed: [],+ confirmed: [],+ retired: [],+ contradictions: [...plan.contradictionTopics],+ moved_to_processed: [],+ ...(dryRun ? { dry_run: true } : {}),+ } satisfies DreamRunSummary);+ }++ // ---- Execute --------------------------------------------------------++ // Snapshot must succeed before any mutation. If it fails, the+ // function throws and nothing changes on disk.+ let snapshotPathStr: string | undefined;+ if (!dryRun) {+ const snap = createSnapshot(vault, runId);+ snapshotPathStr = snap.path;+ }++ // Order of operations matters for the on-disk invariants:+ // 1. Write new unconfirmed preferences (so signal moves can find+ // them).+ // 2. Apply refresh (counters, confidence, promotion) to existing+ // preferences.+ // 3. Move retiring preferences out (after the refresh has had a+ // chance to surface the most recent counters in the retired+ // file). NOTE: refresh skips entries that will retire.+ // 4. Move consumed signals into `processed/`.+ // 5. Emit log entries (noted-redundant, retain-pinned,+ // skip-corrupted-frontmatter, dream summary).+ const moved: string[] = [];++ if (!dryRun) {+ for (const np of plan.newUnconfirmed) {+ writePreference(+ vault,+ {+ slug: np.slug,+ topic: np.topic,+ principle: np.principle,+ created_at: isoSecond(now),+ unconfirmed_until: isoSecond(+ addDays(now, cfg.dream.unconfirmed_window_days),+ ),+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ evidenced_by: np.evidencedBy,+ ...(np.scope ? { scope: np.scope } : {}),+ ...(np.supersedes ? { supersedes: np.supersedes } : {}),+ },+ { overwrite: false },+ );+ }++ for (const update of refresh.updated.values()) {+ writePreference(+ vault,+ {+ slug: update.slug,+ topic: update.topic,+ principle: update.principle,+ created_at: update.created_at,+ unconfirmed_until: update.unconfirmed_until,+ status: update.status,+ evidenced_by: update.evidenced_by,+ confirmed_at: update.confirmed_at,+ applied_count: update.applied_count,+ violated_count: update.violated_count,+ last_evidence_at: update.last_evidence_at,+ confidence: update.confidence,+ pinned: update.pinned,+ ...(update.scope ? { scope: update.scope } : {}),+ },+ { overwrite: true },+ );+ }++ for (const r of plan.retires) {+ const fromPath = preferencePath(vault, r.slug);+ if (!existsSync(fromPath)) continue;+ try {+ moveToRetired(vault, fromPath, r.reason, {+ now,+ retired_by: wikilinkToRun,+ ...(r.supersededBy ? { superseded_by: r.supersededBy } : {}),+ });+ } catch (err) {+ // A retire failure is logged via the `skip-corrupted-frontmatter`+ // pathway only if it stemmed from a parse error during the+ // plan; here the file may have been moved already (rare race).+ // Surface the cause so an operator chasing a missing retire can+ // see which slug tripped.+ process.stderr.write(+ `warning: retire stale pref ${r.slug} failed: ${(err as Error).message}\n`,+ );+ }+ }++ for (const sig of plan.signalsToMove.values()) {+ const dest = processedSignalPath(vault, sig.date, sig.slug);+ try {+ renameSync(sig.path, dest);+ moved.push(sig.id);+ } catch (err) {+ // Best-effort: a missing source signal (already moved) is+ // benign on rerun. Still surface so a real I/O issue is visible.+ process.stderr.write(+ `warning: move signal ${sig.id} to processed/ failed: ${(err as Error).message}\n`,+ );+ }+ }+ } else {+ // Dry-run still reports the move list so the caller's summary is+ // accurate, but it does not touch disk.+ for (const sig of plan.signalsToMove.values()) moved.push(sig.id);+ }++ // Emit log entries: skip-corrupted-frontmatter first (chronological+ // sense: corruption was detected during planning), then per-topic+ // events (noted-redundant), then run summary last.+ if (!dryRun) {+ let logCursorMs = now.getTime();+ const nextStamp = (): string => {+ const ts = new Date(logCursorMs);+ logCursorMs += 1000; // increment per emission so headings stay distinct+ return isoSecond(ts);+ };++ for (const corrupt of scan.corrupted) {+ writeEvent(vault, {+ timestamp: nextStamp(),+ eventType: BRAIN_LOG_EVENT_KIND.skipCorruptedFrontmatter,+ body: {+ path: vaultRelative(corrupt.path, vault),+ },+ });+ }++ for (const noted of plan.notedRedundant) {+ writeEvent(vault, {+ timestamp: nextStamp(),+ eventType: BRAIN_LOG_EVENT_KIND.notedRedundant,+ body: {+ preference: noted.preference,+ signal: noted.signal,+ },+ });+ }++ for (const retain of plan.retainPinned) {+ // `retain-pinned` is not in the strict BrainLogEventKind enum+ // (the design doc names a generic `retire` event with an+ // attempted-but-blocked reason). We log it as a `retire` event+ // with a `blocked: pinned` payload field so the parser+ // round-trips cleanly and the doctor command can flag it.+ writeEvent(vault, {+ timestamp: nextStamp(),+ eventType: BRAIN_LOG_EVENT_KIND.retire,+ body: {+ preference: retain.preference,+ reason: retain.reason,+ blocked: "pinned",+ },+ });+ }++ // Summary event last.+ const newUnconfirmedIds = plan.newUnconfirmed.map((p) => `[[pref-${p.slug}]]`);+ const confirmedIds = Array.from(refresh.confirmed.values()).map(+ (slug) => `[[pref-${slug}]]`,+ );+ const retiredEntries = plan.retires.map(+ (r) => `[[ret-${r.slug}]] (${r.reason})`,+ );+ const summaryBody: Record<string, string | ReadonlyArray<string>> = {+ run_id: runId,+ };+ if (newUnconfirmedIds.length > 0) summaryBody["new_unconfirmed"] = newUnconfirmedIds;+ if (confirmedIds.length > 0) summaryBody["confirmed"] = confirmedIds;+ if (retiredEntries.length > 0) summaryBody["retired"] = retiredEntries;+ if (moved.length > 0) summaryBody["moved_to_processed"] = moved;+ if (plan.contradictionTopics.size > 0) {+ summaryBody["contradictions"] = Array.from(plan.contradictionTopics);+ }++ writeEvent(vault, {+ timestamp: nextStamp(),+ eventType: BRAIN_LOG_EVENT_KIND.dream,+ body: summaryBody,+ });+ }++ // Prune snapshots after the run so the new archive itself counts+ // toward retention.+ if (!dryRun) {+ try {+ pruneSnapshots(vault, cfg.snapshots.retention_count);+ } catch (err) {+ // Pruning is a hygiene step; failure should not turn a+ // successful dream run into an error. The next run will retry.+ // Surface so an operator can spot a recurring disk/permission+ // issue instead of wondering why retention stopped.+ process.stderr.write(+ `warning: prune snapshots failed: ${(err as Error).message}\n`,+ );+ }+ }++ 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 })),+ contradictions: Array.from(plan.contradictionTopics),+ moved_to_processed: moved,+ ...(snapshotPathStr ? { snapshot_path: snapshotPathStr } : {}),+ ...(dryRun+ ? { dry_run: true }+ : { log_path: join(brainDirs(vault).log, `${isoDate(now)}.md`) }),+ } satisfies DreamRunSummary);+}++// ----- Scan ---------------------------------------------------------------++function scanBrain(vault: string): ScanResult {+ const dirs = brainDirs(vault);+ const signals: SignalRecord[] = [];+ const preferences: PreferenceRecord[] = [];+ const retired: RetiredRecord[] = [];+ const corrupted: CorruptedEntry[] = [];++ if (existsSync(dirs.inbox)) {+ for (const name of readdirSync(dirs.inbox)) {+ if (!name.endsWith(".md")) continue;+ const full = join(dirs.inbox, name);+ try {+ const sig = parseSignal(full);+ signals.push({ path: full, signal: sig, active: true });+ } catch {+ corrupted.push({ path: full });+ }+ }+ }+ if (existsSync(dirs.processed)) {+ for (const name of readdirSync(dirs.processed)) {+ if (!name.endsWith(".md")) continue;+ const full = join(dirs.processed, name);+ try {+ const sig = parseSignal(full);+ signals.push({ path: full, signal: sig, active: false });+ } catch {+ corrupted.push({ path: full });+ }+ }+ }+ if (existsSync(dirs.preferences)) {+ for (const name of readdirSync(dirs.preferences)) {+ if (!name.endsWith(".md")) continue;+ const full = join(dirs.preferences, name);+ try {+ const pref = parsePreference(full);+ preferences.push({ path: full, pref });+ } catch {+ corrupted.push({ path: full });+ }+ }+ }+ if (existsSync(dirs.retired)) {+ for (const name of readdirSync(dirs.retired)) {+ if (!name.endsWith(".md")) continue;+ const full = join(dirs.retired, name);+ // Retired files we only need for topic + id (for supersede+ // bookkeeping). We do a lightweight frontmatter parse to avoid+ // the strict folder invariant check failing on permissive setups.+ try {+ const [meta] = parseFrontmatter(full);+ const topic = typeof meta["topic"] === "string" ? meta["topic"] : "";+ const id = typeof meta["id"] === "string" ? meta["id"] : "";+ if (topic && id) {+ retired.push({ path: full, topic, id });+ }+ } catch {+ corrupted.push({ path: full });+ }+ }+ }+ return { signals, preferences, retired, corrupted };+}++// ----- Planning -----------------------------------------------------------++interface PlanState {+ /** Topic slug β planned new unconfirmed preference. */+ readonly newUnconfirmed: NewUnconfirmedPlan[];+ /** Preferences to retire (after refresh). */+ readonly retires: RetirePlan[];+ /** Same-sign signals on active prefs β moved + log event. */+ readonly notedRedundant: NotedRedundantPlan[];+ /** Pinned prefs that would have retired but stay because pinned. */+ readonly retainPinned: RetainPinnedPlan[];+ /** Signal id β record to move out of inbox/. */+ readonly signalsToMove: Map<string, SignalMovePlan>;+ /** Topic slugs flagged contradicted but no transition this run. */+ readonly contradictionTopics: Set<string>;+}++interface NewUnconfirmedPlan {+ readonly slug: string;+ readonly topic: string;+ readonly scope: string | undefined;+ readonly principle: string;+ readonly evidencedBy: ReadonlyArray<string>;+ readonly sign: BrainSignalSign;+ /**+ * Wikilink string (`[[ret-<slug>]]` or `[[pref-<slug>]]`) to the+ * preference this new entry supersedes, if any. Threaded through to+ * `writePreference` so the resulting frontmatter carries+ * `supersedes:` for audit-trail continuity across rebuttals.+ */+ readonly supersedes?: string;+}++interface RetirePlan {+ readonly slug: string;+ readonly reason: BrainRetiredReason;+ readonly supersededBy?: string;+}++interface NotedRedundantPlan {+ readonly preference: string;+ readonly signal: string;+}++interface RetainPinnedPlan {+ readonly preference: string;+ readonly reason: BrainRetiredReason;+}++interface SignalMovePlan {+ readonly id: string;+ readonly date: string;+ readonly slug: string;+ readonly path: string;+}++function emptyPlan(): PlanState {+ return {+ newUnconfirmed: [],+ retires: [],+ notedRedundant: [],+ retainPinned: [],+ signalsToMove: new Map(),+ contradictionTopics: new Set(),+ };+}++function planTopics(+ scan: ScanResult,+ cfg: BrainConfig,+ now: Date,+ _wikilinkToRun: string,+): PlanState {+ void _wikilinkToRun;+ const plan = emptyPlan();+ const reservedSlugs = collectReservedPreferenceSlugs(scan);++ // Group active signals by topic. We only consider active signals for+ // the create/rebut decisions; processed signals stay in the global+ // log via `evidenced_by` already.+ const byTopic = new Map<string, SignalRecord[]>();+ for (const rec of scan.signals) {+ if (!rec.active) continue;+ const topic = rec.signal.topic;+ const arr = byTopic.get(topic);+ if (arr) arr.push(rec);+ else byTopic.set(topic, [rec]);+ }++ // Index existing active preferences by topic.+ const prefByTopic = new Map<string, PreferenceRecord>();+ for (const p of scan.preferences) {+ // The first wins; design doc Β§7.4 invariant says "one preference per+ // topic", so a duplicate would be a doctor-level issue, not a dream+ // concern.+ if (!prefByTopic.has(p.pref.topic)) prefByTopic.set(p.pref.topic, p);+ }++ // Index retired by topic for supersede bookkeeping.+ const retiredByTopic = new Map<string, RetiredRecord[]>();+ for (const r of scan.retired) {+ const arr = retiredByTopic.get(r.topic);+ if (arr) arr.push(r);+ else retiredByTopic.set(r.topic, [r]);+ }++ for (const [topic, sigs] of byTopic) {+ const active = prefByTopic.get(topic);+ if (active) {+ handleSignalsOnActivePref(+ active,+ sigs,+ plan,+ cfg,+ now,+ scan.signals,+ reservedSlugs,+ );+ continue;+ }+ // No active pref for this topic β either promote or note+ // contradiction.+ const windowedSigs = filterWithinWindow(sigs, cfg.dream.contradiction_window_days, now);+ const positives = windowedSigs.filter((s) => s.signal.signal === BRAIN_SIGNAL_SIGN.positive);+ const negatives = windowedSigs.filter((s) => s.signal.signal === BRAIN_SIGNAL_SIGN.negative);+ const dominant = positives.length >= negatives.length ? positives : negatives;+ const minoritySize = Math.min(positives.length, negatives.length);+ const dominantSize = dominant.length - minoritySize; // cancellation+ if (dominantSize >= cfg.dream.candidate_threshold) {+ // Decide supersede: if a retired pref for the same topic exists,+ // wire it through.+ const retiredForTopic = retiredByTopic.get(topic);+ const supersedes = retiredForTopic && retiredForTopic.length > 0+ ? retiredForTopic[0]!.id+ : undefined;+ const sign = dominant[0]!.signal.signal;+ // Slug from topic for the canonical filename, but reserve slugs+ // already present in retired/. Otherwise a superseding preference+ // can be created as `pref-topic` while `ret-topic` already exists;+ // its later retirement would fail trying to overwrite that retired+ // file.+ const slug = allocatePreferencePlanSlug(topic, reservedSlugs);+ const principle = dominant[0]!.signal.principle;+ const scope = dominant[0]!.signal.scope;+ // evidencedBy = wikilinks to ALL active signals (dominant + minority)+ // that contributed to this topic in the window. We deliberately+ // include the minority signals so the audit trail preserves the+ // contradiction story even after the file moves to processed/.+ const evidencedBy = windowedSigs.map((s) => `[[${s.signal.id}]]`);+ plan.newUnconfirmed.push({+ slug,+ topic,+ scope,+ principle,+ evidencedBy,+ sign,+ ...(supersedes ? { supersedes: `[[${supersedes}]]` } : {}),+ });+ // Every contributing signal in the window gets moved.+ for (const s of windowedSigs) {+ recordSignalMove(plan, s);+ }+ } else if (positives.length > 0 && negatives.length > 0) {+ plan.contradictionTopics.add(topic);+ }+ }+ return plan;+}++function handleSignalsOnActivePref(+ active: PreferenceRecord,+ sigs: SignalRecord[],+ plan: PlanState,+ cfg: BrainConfig,+ now: Date,+ allSignals: ReadonlyArray<SignalRecord>,+ reservedSlugs: Set<string>,+): void {+ // Determine the active preference's sign. Order of preference:+ //+ // 1. Walk `evidenced_by` wikilinks and look up each referenced+ // signal in the global scan; the dominant sign among them is+ // the pref's "sign of record". This is the design-correct+ // derivation since the writer baked those evidence pointers in.+ //+ // 2. If no `evidenced_by` resolves (e.g. a hand-crafted pref or a+ // pref whose source signals were manually pruned), look at all+ // historical signals on the same topic in the global scan.+ //+ // 3. If still nothing, assume the active pref is on the OPPOSITE+ // sign of the incoming dominant sign. This makes a unanimous+ // flood of new signals always count as rebuttal β which is the+ // conservative, fail-loud choice: the operator gets a clear+ // rebut/retire signal and can manually intervene if the system+ // misread their intent.+ const signCounts = (records: ReadonlyArray<SignalRecord>): { pos: number; neg: number } => {+ let pos = 0;+ let neg = 0;+ for (const r of records) {+ if (r.signal.signal === BRAIN_SIGNAL_SIGN.positive) pos++;+ else if (r.signal.signal === BRAIN_SIGNAL_SIGN.negative) neg++;+ }+ return { pos, neg };+ };++ const evidenceIds = new Set(+ active.pref.evidenced_by+ .map((wl) => parseWikilink(wl))+ .filter((s): s is string => !!s),+ );+ const evidenceRecords = allSignals.filter((r) => evidenceIds.has(r.signal.id));+ const topicRecords = allSignals.filter((r) => r.signal.topic === active.pref.topic);++ let activeSign: BrainSignalSign;+ if (evidenceRecords.length > 0) {+ const c = signCounts(evidenceRecords);+ activeSign = c.pos >= c.neg ? BRAIN_SIGNAL_SIGN.positive : BRAIN_SIGNAL_SIGN.negative;+ } else if (topicRecords.length > sigs.length) {+ // There are processed signals for this topic that are NOT among+ // the active inbox set β use them.+ const historical = topicRecords.filter((r) => !sigs.includes(r));+ const c = signCounts(historical);+ activeSign = c.pos >= c.neg ? BRAIN_SIGNAL_SIGN.positive : BRAIN_SIGNAL_SIGN.negative;+ } else {+ // Fallback: assume the active pref is OPPOSITE to the incoming+ // dominant sign. A unanimous flood thus reads as rebuttal.+ const c = signCounts(sigs);+ activeSign =+ c.pos > c.neg ? BRAIN_SIGNAL_SIGN.negative : BRAIN_SIGNAL_SIGN.positive;+ }++ const oppositeSign: BrainSignalSign =+ activeSign === BRAIN_SIGNAL_SIGN.positive+ ? BRAIN_SIGNAL_SIGN.negative+ : BRAIN_SIGNAL_SIGN.positive;++ const windowed = filterWithinWindow(sigs, cfg.dream.contradiction_window_days, now);+ const sameSign = windowed.filter((s) => s.signal.signal === activeSign);+ const opposing = windowed.filter((s) => s.signal.signal === oppositeSign);++ // Same-sign β note redundant + move to processed.+ for (const s of sameSign) {+ plan.notedRedundant.push({+ preference: `[[${active.pref.id}]]`,+ signal: `[[${s.signal.id}]]`,+ });+ recordSignalMove(plan, s);+ }++ // Opposite-sign β accumulate toward rebuttal.+ if (opposing.length >= cfg.dream.candidate_threshold) {+ const slug = active.pref.id.startsWith("pref-")+ ? active.pref.id.slice("pref-".length)+ : active.pref.id;+ if (isPinned(active.pref)) {+ plan.retainPinned.push({+ preference: `[[${active.pref.id}]]`,+ reason: BRAIN_RETIRED_REASON.rebutted,+ });+ // Rebuttal signals on a pinned pref still get moved out β they+ // were addressed (the system saw them) and clogging the inbox+ // doesn't help.+ for (const s of opposing) recordSignalMove(plan, s);+ } else {+ plan.retires.push({+ slug,+ reason: BRAIN_RETIRED_REASON.rebutted,+ });+ for (const s of opposing) recordSignalMove(plan, s);+ // Create a new unconfirmed pref for the new direction.+ // Build a fresh slug to avoid filename collision with the+ // retiring pref (which lives under preferences/<slug>.md and+ // will move to retired/<slug>.md). The simplest scheme: the+ // same slug, since `moveToRetired` unlinks the source first.+ // For safety against a half-completed move, we suffix with+ // `-rebut`.+ const newSlug = allocatePreferencePlanSlug(`${slug}-rebut`, reservedSlugs);+ const principle = opposing[0]!.signal.principle;+ const scope = opposing[0]!.signal.scope;+ const evidencedBy = opposing.map((s) => `[[${s.signal.id}]]`);+ plan.newUnconfirmed.push({+ slug: newSlug,+ topic: active.pref.topic,+ scope,+ principle,+ evidencedBy,+ sign: oppositeSign,+ supersedes: `[[${active.pref.id}]]`,+ });+ }+ } else if (opposing.length > 0) {+ plan.contradictionTopics.add(active.pref.topic);+ }+}++function collectReservedPreferenceSlugs(scan: ScanResult): Set<string> {+ const out = new Set<string>();+ for (const p of scan.preferences) {+ const slug = preferenceSlugFromId(p.pref.id, "pref-");+ if (slug) out.add(slug);+ }+ for (const r of scan.retired) {+ const slug = preferenceSlugFromId(r.id, "ret-");+ if (slug) out.add(slug);+ }+ return out;+}++function preferenceSlugFromId(id: string, prefix: "pref-" | "ret-"): string | null {+ return id.startsWith(prefix) && id.length > prefix.length+ ? id.slice(prefix.length)+ : null;+}++function allocatePreferencePlanSlug(base: string, reserved: Set<string>): string {+ let candidate = base;+ let suffix = 2;+ while (reserved.has(candidate)) {+ candidate = `${base}-${suffix}`;+ suffix++;+ }+ reserved.add(candidate);+ return candidate;+}++function recordSignalMove(plan: PlanState, rec: SignalRecord): void {+ if (!rec.active) return;+ const id = rec.signal.id;+ if (plan.signalsToMove.has(id)) return;+ // Derive date + slug from the id (`sig-YYYY-MM-DD-<slug>`).+ const m = /^sig-(\d{4}-\d{2}-\d{2})-(.+)$/.exec(id);+ if (!m) return;+ plan.signalsToMove.set(id, {+ id,+ date: m[1]!,+ slug: m[2]!,+ path: rec.path,+ });+}++function filterWithinWindow(+ sigs: SignalRecord[],+ windowDays: number,+ now: Date,+): SignalRecord[] {+ const minTime = now.getTime() - windowDays * 24 * 3600 * 1000;+ return sigs.filter((s) => {+ const t = Date.parse(s.signal.created_at);+ return Number.isFinite(t) && t >= minTime;+ });+}++// ----- Refresh + promote --------------------------------------------------++interface RefreshUpdate {+ readonly slug: string;+ readonly topic: string;+ readonly scope?: string;+ readonly principle: string;+ readonly created_at: string;+ readonly unconfirmed_until: string;+ readonly status: typeof BRAIN_PREFERENCE_STATUS[keyof typeof BRAIN_PREFERENCE_STATUS];+ readonly evidenced_by: ReadonlyArray<string>;+ readonly confirmed_at: string | null;+ readonly applied_count: number;+ readonly violated_count: number;+ readonly last_evidence_at: string | null;+ readonly confidence: BrainConfidence;+ readonly pinned: boolean;+}++interface RefreshResult {+ /** Slugs transitioning unconfirmed β confirmed in THIS run. */+ readonly confirmed: Set<string>;+ /** Slug β full updated frontmatter to write. */+ readonly updated: Map<string, RefreshUpdate>;+}++interface ApplyEvidenceEntry {+ readonly pref_slug: string;+ readonly timestamp: string;+ readonly result: typeof BRAIN_APPLY_RESULT[keyof typeof BRAIN_APPLY_RESULT];+}++function scanApplyEvidence(vault: string): ApplyEvidenceEntry[] {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.log)) return [];+ const out: ApplyEvidenceEntry[] = [];+ for (const name of readdirSync(dirs.log)) {+ if (!name.endsWith(".md")) continue;+ const date = name.slice(0, -3);+ if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;+ const { entries } = parseLogDay(vault, date);+ for (const e of entries) {+ if (e.eventType !== BRAIN_LOG_EVENT_KIND.applyEvidence) continue;+ const prefRaw = e.body["preference"];+ const result = e.body["result"];+ if (typeof prefRaw !== "string" || typeof result !== "string") continue;+ if (result !== BRAIN_APPLY_RESULT.applied && result !== BRAIN_APPLY_RESULT.violated) continue;+ // Parse `[[pref-slug]]` β slug.+ const target = parseWikilink(prefRaw);+ if (!target || !target.startsWith("pref-")) continue;+ out.push({+ pref_slug: target.slice("pref-".length),+ timestamp: e.timestamp,+ result: result as ApplyEvidenceEntry["result"],+ });+ }+ }+ // Stable order: by timestamp ascending. Multiple entries at the same+ // second keep their parse order (parseLogDay returns insertion order).+ out.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));+ return out;+}++function planRefresh(+ scan: ScanResult,+ evidence: ApplyEvidenceEntry[],+ cfg: BrainConfig,+ now: Date,+ plan: PlanState,+): RefreshResult {+ const confirmed = new Set<string>();+ const updated = new Map<string, RefreshUpdate>();++ // Index evidence by slug.+ const bySlug = new Map<string, ApplyEvidenceEntry[]>();+ for (const e of evidence) {+ const arr = bySlug.get(e.pref_slug);+ if (arr) arr.push(e);+ else bySlug.set(e.pref_slug, [e]);+ }++ // Slugs that will retire this run β we skip refresh for those so the+ // retired/ snapshot reflects the pre-refresh counters (which is the+ // existing test expectation in moveToRetired).+ const retiringSlugs = new Set(plan.retires.map((r) => r.slug));++ for (const rec of scan.preferences) {+ const slug = rec.pref.id.startsWith("pref-")+ ? rec.pref.id.slice("pref-".length)+ : rec.pref.id;+ if (retiringSlugs.has(slug)) continue;++ const ev = bySlug.get(slug) ?? [];+ const applied = ev.filter((e) => e.result === BRAIN_APPLY_RESULT.applied).length;+ const violated = ev.filter((e) => e.result === BRAIN_APPLY_RESULT.violated).length;+ const lastEvidence = ev.length > 0 ? ev[ev.length - 1]!.timestamp : null;+ const firstApplied = ev.find((e) => e.result === BRAIN_APPLY_RESULT.applied);++ let status = rec.pref.status;+ let confirmedAt = rec.pref.confirmed_at;+ if (status === BRAIN_PREFERENCE_STATUS.unconfirmed && firstApplied) {+ status = BRAIN_PREFERENCE_STATUS.confirmed;+ confirmedAt = firstApplied.timestamp;+ confirmed.add(slug);+ }++ const confidenceValue = computeConfidence(+ applied,+ violated,+ lastEvidence,+ cfg,+ now,+ );++ // Only emit an update if something actually changed. This matters+ // for the idempotency invariant: a no-op rerun on the same fixture+ // must not rewrite preference files (the file mtime would change+ // but byte content would be identical; writing anyway is wasted+ // I/O and triggers an unnecessary log entry).+ const changed =+ applied !== rec.pref.applied_count ||+ violated !== rec.pref.violated_count ||+ lastEvidence !== rec.pref.last_evidence_at ||+ status !== rec.pref.status ||+ confirmedAt !== rec.pref.confirmed_at ||+ confidenceValue !== rec.pref.confidence;+ if (!changed) continue;++ updated.set(slug, {+ slug,+ topic: rec.pref.topic,+ ...(rec.pref.scope ? { scope: rec.pref.scope } : {}),+ principle: rec.pref.principle,+ created_at: rec.pref.created_at,+ unconfirmed_until: rec.pref.unconfirmed_until,+ status,+ evidenced_by: rec.pref.evidenced_by,+ confirmed_at: confirmedAt,+ applied_count: applied,+ violated_count: violated,+ last_evidence_at: lastEvidence,+ confidence: confidenceValue,+ pinned: rec.pref.pinned,+ });+ }++ return { confirmed, updated };+}++function computeConfidence(+ applied: number,+ violated: number,+ lastEvidenceAt: string | null,+ cfg: BrainConfig,+ now: Date,+): BrainConfidence {+ // From Β§7.4:+ // if applied <= low_max_applied or (applied > 0 and violated >= applied):+ // confidence = low+ // elif applied >= high_min_applied and violated == 0 and fresh:+ // confidence = high+ // else:+ // confidence = medium+ if (applied <= cfg.confidence.low_max_applied) return BRAIN_CONFIDENCE.low;+ if (applied > 0 && violated >= applied) return BRAIN_CONFIDENCE.low;+ let fresh = false;+ if (lastEvidenceAt) {+ const ageMs = now.getTime() - Date.parse(lastEvidenceAt);+ const freshLimitMs =+ cfg.retire.stale_evidence_days *+ cfg.confidence.high_freshness_factor *+ 24 *+ 3600 *+ 1000;+ fresh = Number.isFinite(ageMs) && ageMs < freshLimitMs;+ }+ if (applied >= cfg.confidence.high_min_applied && violated === 0 && fresh) {+ return BRAIN_CONFIDENCE.high;+ }+ return BRAIN_CONFIDENCE.medium;+}++// ----- Auto-retires (expired-unconfirmed, stale-no-evidence) --------------++function planAutoRetires(+ scan: ScanResult,+ cfg: BrainConfig,+ now: Date,+ plan: PlanState,+ refresh: RefreshResult,+): void {+ for (const rec of scan.preferences) {+ const slug = rec.pref.id.startsWith("pref-")+ ? rec.pref.id.slice("pref-".length)+ : rec.pref.id;+ // Already planned to retire (rebutted)? Skip.+ if (plan.retires.some((r) => r.slug === slug)) continue;++ // Use the refreshed status/confirmed_at if available β a pref+ // promoted to confirmed in THIS run should be eligible for stale+ // retire only if its (yet-to-be-refreshed) last_evidence_at is+ // actually old. We branch on the post-refresh shape.+ const refreshed = refresh.updated.get(slug);+ const effectiveStatus = refreshed ? refreshed.status : rec.pref.status;+ const effectiveLastEvidence = refreshed+ ? refreshed.last_evidence_at+ : rec.pref.last_evidence_at;++ if (effectiveStatus === BRAIN_PREFERENCE_STATUS.unconfirmed) {+ const deadline = Date.parse(rec.pref.unconfirmed_until);+ if (Number.isFinite(deadline) && now.getTime() > deadline) {+ if (isPinned(rec.pref)) {+ plan.retainPinned.push({+ preference: `[[${rec.pref.id}]]`,+ reason: BRAIN_RETIRED_REASON.expiredUnconfirmed,+ });+ } else {+ plan.retires.push({+ slug,+ reason: BRAIN_RETIRED_REASON.expiredUnconfirmed,+ });+ // Remove the refresh update β no point writing immediately+ // before moving to retired/.+ refresh.updated.delete(slug);+ }+ }+ continue;+ }++ // Confirmed β stale-no-evidence check.+ if (effectiveStatus === BRAIN_PREFERENCE_STATUS.confirmed) {+ if (!effectiveLastEvidence) {+ // Confirmed with no evidence at all? Shouldn't happen, but+ // gate on the same staleness rule using `confirmed_at`. We+ // measure from confirmation in that case (cheaper than a+ // hand-crafted invariant check).+ const confirmedAt = refreshed+ ? refreshed.confirmed_at+ : rec.pref.confirmed_at;+ if (!confirmedAt) continue;+ const days = daysBetween(Date.parse(confirmedAt), now.getTime());+ if (days > cfg.retire.stale_evidence_days) {+ if (isPinned(rec.pref)) {+ plan.retainPinned.push({+ preference: `[[${rec.pref.id}]]`,+ reason: BRAIN_RETIRED_REASON.staleNoEvidence,+ });+ } else {+ plan.retires.push({+ slug,+ reason: BRAIN_RETIRED_REASON.staleNoEvidence,+ });+ refresh.updated.delete(slug);+ }+ }+ continue;+ }+ const days = daysBetween(Date.parse(effectiveLastEvidence), now.getTime());+ if (days > cfg.retire.stale_evidence_days) {+ if (isPinned(rec.pref)) {+ plan.retainPinned.push({+ preference: `[[${rec.pref.id}]]`,+ reason: BRAIN_RETIRED_REASON.staleNoEvidence,+ });+ } else {+ plan.retires.push({+ slug,+ reason: BRAIN_RETIRED_REASON.staleNoEvidence,+ });+ refresh.updated.delete(slug);+ }+ }+ }+ }+}++// ----- Signal moves -------------------------------------------------------++function planSignalMoves(scan: ScanResult, plan: PlanState): void {+ // All active signals whose topic now corresponds to a planned new+ // pref or an active pref were already enqueued by the topic-loop /+ // active-pref handler. This function exists for the Β§7.3 step that+ // says "Move consumed signals out of inbox/": we cover the case+ // where a signal references a preference that already exists (the+ // active-pref path), and the case where a signal is part of a fresh+ // new_unconfirmed (the topic-loop path). Both already populated+ // `plan.signalsToMove`. Nothing additional needed here today.+ void scan;+ void plan;+}++// ----- Helpers ------------------------------------------------------------++function writeEvent(vault: string, event: BrainLogEntry): void {+ appendLogEvent(vault, event);+}++function addDays(d: Date, days: number): Date {+ return new Date(d.getTime() + days * 24 * 3600 * 1000);+}++function daysBetween(thenMs: number, nowMs: number): number {+ if (!Number.isFinite(thenMs)) return 0;+ return (nowMs - thenMs) / (24 * 3600 * 1000);+}++function formatRunId(d: Date): string {+ // dream-YYYY-MM-DD-HHMMSS+ const yyyy = d.getUTCFullYear().toString().padStart(4, "0");+ const mm = (d.getUTCMonth() + 1).toString().padStart(2, "0");+ const dd = d.getUTCDate().toString().padStart(2, "0");+ const hh = d.getUTCHours().toString().padStart(2, "0");+ const mi = d.getUTCMinutes().toString().padStart(2, "0");+ const ss = d.getUTCSeconds().toString().padStart(2, "0");+ return `dream-${yyyy}-${mm}-${dd}-${hh}${mi}${ss}`;+}++// Silence "unused" warnings for symbols exported only via barrel.+void basename;diff --git a/src/core/brain/index.ts b/src/core/brain/index.tsnew file mode 100644index 00000000..b711d784--- /dev/null+++ b/src/core/brain/index.ts@@ -0,0 +1,100 @@+/**+ * Public surface of the Brain layer.+ *+ * CLI and MCP entry points (added in Tasks 6 and 7) import from this+ * barrel. Internal modules remain importable directly when a tighter+ * coupling is intentional, but adapters should prefer this surface so+ * private helpers can move without breaking call sites.+ */++// ----- Types ----------------------------------------------------------------+export type {+ BrainSignal,+ BrainPreference,+ BrainRetired,+ BrainLogEvent,+ BrainLogEventBase,+ BrainDreamLogEvent,+ BrainApplyEvidenceLogEvent,+ BrainFeedbackLogEvent,+ BrainForceConfirmedLogEvent,+ BrainRejectLogEvent,+ BrainPromoteLogEvent,+ BrainRetireLogEvent,+ BrainNotedRedundantLogEvent,+ BrainSkipCorruptedLogEvent,+ BrainPinLogEvent,+ BrainRollbackLogEvent,+ BrainSignalSign,+ BrainPreferenceStatus,+ BrainConfidence,+ BrainRetiredReason,+ BrainApplyResult,+ BrainLogEventKind,+ BrainConfig,+ BrainDreamConfig,+ BrainRetireConfig,+ BrainConfidenceConfig,+ BrainSnapshotsConfig,+} from "./types.ts";++export {+ BRAIN_SIGNAL_SIGN,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_CONFIDENCE,+ BRAIN_RETIRED_REASON,+ BRAIN_APPLY_RESULT,+ BRAIN_LOG_EVENT_KIND,+} from "./types.ts";++// ----- Path helpers ---------------------------------------------------------+export {+ brainDirs,+ brainConfigPath,+ brainManualPath,+ signalPath,+ processedSignalPath,+ preferencePath,+ retiredPath,+ logPath,+ snapshotsDir,+ snapshotPath,+ allocateSlug,+ validateSlug,+ validateIsoDate,+ validateRunId,+ brainVaultRelative,+ ensureInsideVault,+ vaultRelative,+} from "./paths.ts";++export type {+ BrainDirs,+ AllocateSlugOptions,+ AllocateSlugResult,+} from "./paths.ts";++// ----- Configuration --------------------------------------------------------+export {+ DEFAULT_BRAIN_CONFIG,+ DEFAULT_BRAIN_CONFIG_YAML,+ BRAIN_CONFIG_SUPPORTED_VERSIONS,+ BrainConfigError,+ loadBrainConfig,+ loadBrainConfigDetailed,+ validateBrainConfig,+ validateBrainConfigDetailed,+ parseBrainYaml,+} from "./policy.ts";++export type {+ BrainConfigLoadWarning,+ LoadBrainConfigResult,+ ValidateResult,+} from "./policy.ts";++// ----- Time helpers ---------------------------------------------------------+export { isoSecond, isoDate } from "./time.ts";++// ----- Wikilink helpers -----------------------------------------------------+export { normaliseWikilinkTarget, parseWikilink } from "./wikilink.ts";diff --git a/src/core/brain/init.ts b/src/core/brain/init.tsnew file mode 100644index 00000000..1ed6256e--- /dev/null+++ b/src/core/brain/init.ts@@ -0,0 +1,261 @@+/**+ * Brain layer bootstrap.+ *+ * Creates the `<vault>/Brain/` directory tree, drops the default+ * `_brain.yaml`, and renders the two Markdown templates the agent reads+ * each session: `Brain/_BRAIN.md` (operating manual for the writable+ * layer) and `AI Wiki/_OPEN_SECOND_BRAIN.md` (Brain-first vault+ * overview that replaces the legacy file).+ *+ * Behaviour summary (design doc Β§15 Task 5, Β§12.1):+ *+ * - Directory creation is idempotent.+ * - `Brain/_brain.yaml` and `Brain/_BRAIN.md` are written on first+ * run; subsequent runs without `force` skip them. `force: true`+ * overwrites both.+ * - `AI Wiki/_OPEN_SECOND_BRAIN.md` is **always** overwritten on every+ * bootstrap, regardless of `force`. The design owner accepted this+ * trade-off at near-zero current user count: the file is the+ * instruction surface agents read first; stale copy hurts more+ * than the (negligible) risk of overwriting a manual edit. The+ * legacy file's prior content is not backed up.+ * - Bootstrap refuses to run if the machine-level plugin config (the+ * one `o2b init` writes) is missing, since callers must register+ * the vault before any Brain operation. The error message names+ * `o2b init` as the fix.+ * - Every write is routed through {@link atomicWriteFileSync} so an+ * interrupted run leaves either the prior version or the new one,+ * never a torn hybrid.+ */++import { existsSync, mkdirSync, readFileSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import { defaultConfigPath } from "../config.ts";+import { atomicWriteFileSync } from "../fs-atomic.ts";+import {+ brainConfigPath,+ brainDirs,+ brainManualPath,+ vaultRelative,+} from "./paths.ts";+import { DEFAULT_BRAIN_CONFIG_YAML } from "./policy.ts";+import type { BrainConfig } from "./types.ts";+import { DEFAULT_BRAIN_CONFIG } from "./policy.ts";++// Resolve template paths relative to this source file. `import.meta.url`+// is stable under both `bun run` (TS source) and any future build that+// keeps the template files alongside the bundled JS.+const TEMPLATE_DIR = resolve(+ dirname(fileURLToPath(import.meta.url)),+ "templates",+);++const BRAIN_MANUAL_TEMPLATE_PATH = join(TEMPLATE_DIR, "_BRAIN.md.tpl");+const LEGACY_OVERVIEW_TEMPLATE_PATH = join(+ TEMPLATE_DIR,+ "_OPEN_SECOND_BRAIN.md.tpl",+);++/** Vault-relative target for the legacy-overview replacement. */+const LEGACY_OVERVIEW_REL_PATH = join("AI Wiki", "_OPEN_SECOND_BRAIN.md");++export interface BootstrapBrainOptions {+ /** Overwrite `_brain.yaml` and `_BRAIN.md` if they already exist. */+ readonly force?: boolean;+ /**+ * Injection seam for deterministic tests. Currently unused in the+ * rendered output (templates carry static text), but reserved so+ * future timestamped substitutions stay test-friendly.+ */+ readonly now?: Date;+ /**+ * Override path of the machine-level plugin config. When unset, the+ * lookup chain in {@link defaultConfigPath} applies+ * (`OPEN_SECOND_BRAIN_CONFIG` env β XDG β `~/.config`).+ */+ readonly configPath?: string;+}++export interface BootstrapBrainResult {+ /** Vault-relative paths newly written. */+ readonly created: ReadonlyArray<string>;+ /** Vault-relative paths whose existing content was replaced. */+ readonly overwritten: ReadonlyArray<string>;+ /** Vault-relative paths left untouched because they already existed. */+ readonly skipped: ReadonlyArray<string>;+}++/**+ * Bootstrap `<vault>/Brain/` and the legacy-overview replacement.+ *+ * @throws Error when the machine-level plugin config does not exist;+ * the message names `o2b init` as the fix and the CLI surfaces it+ * as exit code 1.+ */+export function bootstrapBrain(+ vault: string,+ opts: BootstrapBrainOptions = {},+): BootstrapBrainResult {+ const force = opts.force ?? false;+ const configPath = opts.configPath ?? defaultConfigPath();++ // Refuse to run before the vault has been registered. The machine+ // config carries the `vault:` field every subsequent `o2b brain *`+ // command relies on; bootstrapping without it would leave the user+ // with a half-wired install that fails on the first invocation+ // with a confusing "vault not configured" error far from the cause.+ if (!existsSync(configPath)) {+ throw new Error(+ `open-second-brain plugin config not found at ${configPath}; ` ++ "run `o2b init` first to register the vault",+ );+ }++ const created: string[] = [];+ const overwritten: string[] = [];+ const skipped: string[] = [];++ // 1. Directories. mkdirSync({ recursive: true }) is idempotent and+ // does not throw on existing paths, so we do not track create+ // counts for directories β only files end up in the report.+ const dirs = brainDirs(vault);+ for (const dir of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ dirs.snapshots,+ ]) {+ mkdirSync(dir, { recursive: true });+ }++ // 2. `_brain.yaml` β default config.+ const brainYamlPath = brainConfigPath(vault);+ const brainYamlRel = vaultRelative(brainYamlPath, vault);+ if (existsSync(brainYamlPath)) {+ if (force) {+ atomicWriteFileSync(brainYamlPath, DEFAULT_BRAIN_CONFIG_YAML);+ overwritten.push(brainYamlRel);+ } else {+ skipped.push(brainYamlRel);+ }+ } else {+ atomicWriteFileSync(brainYamlPath, DEFAULT_BRAIN_CONFIG_YAML);+ created.push(brainYamlRel);+ }++ // 3. `Brain/_BRAIN.md` β operating manual rendered from template.+ const manualPath = brainManualPath(vault);+ const manualRel = vaultRelative(manualPath, vault);+ const manualBody = renderTemplate(+ readTemplate(BRAIN_MANUAL_TEMPLATE_PATH),+ buildSubstitutions(vault, DEFAULT_BRAIN_CONFIG),+ );+ if (existsSync(manualPath)) {+ if (force) {+ atomicWriteFileSync(manualPath, manualBody);+ overwritten.push(manualRel);+ } else {+ skipped.push(manualRel);+ }+ } else {+ atomicWriteFileSync(manualPath, manualBody);+ created.push(manualRel);+ }++ // 4. `AI Wiki/_OPEN_SECOND_BRAIN.md` β always overwritten. The+ // parent directory may not exist if the caller never ran+ // `o2b init` against this vault directly (e.g. they registered a+ // different vault path in the machine config and ran Brain init+ // elsewhere). We create it on demand: the file is meaningful even+ // without the rest of `AI Wiki/`.+ const overviewPath = join(vault, LEGACY_OVERVIEW_REL_PATH);+ const overviewRel = LEGACY_OVERVIEW_REL_PATH;+ mkdirSync(dirname(overviewPath), { recursive: true });+ const overviewBody = renderTemplate(+ readTemplate(LEGACY_OVERVIEW_TEMPLATE_PATH),+ buildSubstitutions(vault, DEFAULT_BRAIN_CONFIG),+ );+ const overviewExisted = existsSync(overviewPath);+ atomicWriteFileSync(overviewPath, overviewBody);+ if (overviewExisted) {+ overwritten.push(overviewRel);+ } else {+ created.push(overviewRel);+ }++ return { created, overwritten, skipped };+}++/**+ * Read a template file from disk. Wrapped so a missing template (which+ * would indicate a broken build / packaging) surfaces with a clear+ * pointer rather than the bare `ENOENT` Node throws.+ */+function readTemplate(path: string): string {+ try {+ return readFileSync(path, "utf8");+ } catch (err) {+ const message = err instanceof Error ? err.message : String(err);+ throw new Error(+ `Failed to load Brain template at ${path}: ${message}. ` ++ "This indicates a broken open-second-brain install β the " ++ "src/core/brain/templates/ directory must ship alongside init.ts.",+ );+ }+}++/**+ * Compute `{{key}}` substitutions for the current vault. Kept tiny on+ * purpose: the templates carry static prose and only need to thread a+ * couple of contextual values (vault name, schema version). Adding more+ * substitutions later is a one-line change here.+ */+function buildSubstitutions(+ vault: string,+ config: BrainConfig,+): ReadonlyMap<string, string> {+ return new Map<string, string>([+ ["vault_name", vaultDisplayName(vault)],+ ["schema_version", String(config.schema_version)],+ ]);+}++/**+ * Apply `{{key}}` substitutions to `template`. Unknown placeholders are+ * left intact so a typo surfaces in the rendered file (and in the+ * line-count test) rather than disappearing silently.+ */+function renderTemplate(+ template: string,+ substitutions: ReadonlyMap<string, string>,+): string {+ let out = template;+ for (const [key, value] of substitutions) {+ // Escape regex metachars in the key in case future keys carry+ // anything other than `[a-z_]`. Today they don't; defensive anyway.+ const pattern = new RegExp(`\\{\\{\\s*${escapeRegex(key)}\\s*\\}\\}`, "g");+ out = out.replace(pattern, value);+ }+ return out;+}++function escapeRegex(text: string): string {+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+}++/**+ * Best-effort display name for the vault: the trailing directory name+ * with separators stripped. Falls back to the literal `Second Brain`+ * if the vault path has no usable basename.+ */+function vaultDisplayName(vault: string): string {+ const parts = vault.split(/[\\/]/).filter((p) => p.length > 0);+ const last = parts.length > 0 ? parts[parts.length - 1]! : "";+ return last !== "" ? last : "Second Brain";+}+diff --git a/src/core/brain/log.ts b/src/core/brain/log.tsnew file mode 100644index 00000000..faffe9a8--- /dev/null+++ b/src/core/brain/log.ts@@ -0,0 +1,385 @@+/**+ * Brain log (`Brain/log/<YYYY-MM-DD>.md`) parser and appender.+ *+ * The log is the audit trail of every state-changing Brain operation.+ * One Markdown file per UTC day; events appear as level-2 headings+ * formatted as `## <HH:MM:SS>Z β <event-kind>` followed by a bullet+ * list of `- <key>: <value>` lines. Lists are encoded as repeated+ * `- key:` entries with sub-bullets (the simple parser accepts both+ * `- key: value` and the indented sub-bullet form for arrays).+ *+ * Two operations:+ *+ * - {@link parseLogDay} reads one day's file and returns an array of+ * {@link BrainLogEntry}. Malformed entries (broken header, invalid+ * bullet shape) are skipped and surfaced via the `warnings` array+ * so the dream loop and digest never blow up on a partially-edited+ * log. Returns an empty array when the file does not exist.+ *+ * - {@link appendLogEvent} writes a new event to today's log. If the+ * file is absent, it is created with a canonical frontmatter+ * header (`kind: brain-log`, `date`, `tags`) and the title line.+ * Subsequent appends preserve previous bytes verbatim β the+ * log is append-only. Atomicity is achieved by reading the+ * existing contents, appending the new block, and writing the+ * result back through `fs-atomic` in one shot.+ */++import { existsSync, readFileSync } from "node:fs";++import { atomicWriteFileSync } from "../fs-atomic.ts";+import { logPath, validateIsoDate } from "./paths.ts";+import {+ BRAIN_LOG_EVENT_KIND,+ type BrainLogEventKind,+} from "./types.ts";++// ----- Public types ---------------------------------------------------------++/** Parsed bullet payload of a single log entry. */+export type BrainLogEntryPayload = Readonly<+ Record<string, string | ReadonlyArray<string>>+>;++/**+ * A parsed log entry. `timestamp` is the full ISO-8601 UTC moment+ * reconstructed from the file's `date` and the heading's `HH:MM:SS`+ * stamp. `body` keeps the bullet payload verbatim (string for single+ * values, string[] for repeated keys).+ */+export interface BrainLogEntry {+ readonly timestamp: string;+ readonly eventType: BrainLogEventKind;+ readonly body: BrainLogEntryPayload;+}++/** Warning surfaced by {@link parseLogDay} for a malformed sub-block. */+export interface BrainLogParseWarning {+ readonly path: string;+ readonly lineNumber: number;+ readonly message: string;+}++export interface ParseLogDayResult {+ readonly entries: ReadonlyArray<BrainLogEntry>;+ readonly warnings: ReadonlyArray<BrainLogParseWarning>;+}++export interface AppendLogEventResult {+ readonly logPath: string;+}++// ----- Constants ------------------------------------------------------------++const EVENT_KIND_VALUES: ReadonlySet<string> = new Set(+ Object.values(BRAIN_LOG_EVENT_KIND),+);++// `## HH:MM:SSZ β <kind>` β both the em dash (β) and the hyphen are+// accepted to tolerate hand-edits. The mandatory `Z` after the time+// reflects the design doc's "UTC time" formatting (Β§5.5 example).+const HEADER_RE = /^##\s+(\d{2}):(\d{2}):(\d{2})Z\s+[β-]\s+([a-z][a-z0-9-]*)\s*$/;++// Bullet keys are limited to ASCII identifiers (with `_`) plus+// hyphens. We accept any text after the colon, including wikilinks,+// quoted strings, and multi-word values β the parser does not try to+// interpret them, only to record the key/value split.+const BULLET_RE = /^-\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/;++// Sub-bullets nest underneath a parent bullet that ends with a bare+// colon (no value). The leading whitespace varies in real-world+// edits; we accept 2-or-more spaces or one or more tabs.+const SUB_BULLET_RE = /^(?:\s{2,}|\t+)-\s+(.+)$/;++// ----- Public API -----------------------------------------------------------++/**+ * Parse `Brain/log/<date>.md` if present. Returns an empty array when+ * the file does not exist β there is no Brain log for that day yet.+ *+ * `parseLogDay` is tolerant of garbage: malformed headers, unknown+ * event kinds, or stray bullets get reported as warnings and the rest+ * of the file is still returned. This keeps the dream loop alive even+ * when a manual edit corrupts a single block.+ */+export function parseLogDay(vault: string, date: string): ParseLogDayResult {+ const validDate = validateIsoDate(date);+ const path = logPath(vault, validDate);+ if (!existsSync(path)) {+ return { entries: [], warnings: [] };+ }+ let text: string;+ try {+ text = readFileSync(path, "utf8");+ } catch {+ return { entries: [], warnings: [] };+ }++ const entries: BrainLogEntry[] = [];+ const warnings: BrainLogParseWarning[] = [];++ // Strip the YAML frontmatter and the top-level title to expose the+ // event blocks. We do this with a manual scan rather than the+ // frontmatter parser because we need the raw line numbers for the+ // warning trail.+ const lines = text.split(/\r?\n/);+ let cursor = 0;+ if (lines[0]?.trimEnd() === "---") {+ cursor = 1;+ while (cursor < lines.length && lines[cursor]?.trimEnd() !== "---") {+ cursor++;+ }+ if (cursor < lines.length) cursor++; // skip closing '---'+ }++ // Each event block starts at a `## ...` line and ends at the next+ // `## ...` or EOF. We collect them in encounter order so the+ // caller's "stable order" guarantee is honoured.+ while (cursor < lines.length) {+ const line = lines[cursor]!;+ if (!line.startsWith("## ")) {+ cursor++;+ continue;+ }+ const headerLineNumber = cursor + 1;+ const header = HEADER_RE.exec(line);+ if (!header) {+ warnings.push({+ path,+ lineNumber: headerLineNumber,+ message: `malformed event header: ${line}`,+ });+ cursor++;+ continue;+ }+ const hh = header[1]!;+ const mm = header[2]!;+ const ss = header[3]!;+ const kindStr = header[4]!;+ if (!EVENT_KIND_VALUES.has(kindStr)) {+ warnings.push({+ path,+ lineNumber: headerLineNumber,+ message: `unknown event kind: ${kindStr}`,+ });+ cursor++;+ // Skip the malformed block's body so we don't try to parse its+ // bullets as a top-level event.+ while (cursor < lines.length && !lines[cursor]!.startsWith("## ")) {+ cursor++;+ }+ continue;+ }++ // Read bullets until the next event header or EOF.+ cursor++;+ const blockStart = cursor;+ while (cursor < lines.length && !lines[cursor]!.startsWith("## ")) {+ cursor++;+ }+ const blockEnd = cursor;++ const { payload, blockWarnings } = parseBulletBlock(+ lines.slice(blockStart, blockEnd),+ blockStart + 1,+ path,+ );+ for (const w of blockWarnings) warnings.push(w);++ entries.push({+ timestamp: `${validDate}T${hh}:${mm}:${ss}Z`,+ eventType: kindStr as BrainLogEventKind,+ body: Object.freeze(payload),+ });+ }++ return { entries, warnings };+}++/**+ * Append a new event to the log for the day of `event.timestamp`. If+ * the log file does not yet exist, it is created with the canonical+ * frontmatter + title header; otherwise the existing file is read,+ * concatenated with the new block, and written back atomically. We+ * never edit prior blocks β append-only is the contract.+ *+ * Two writes happening at the same UTC second receive the same+ * `<HH:MM:SS>` header; the on-disk order is the order of calls to+ * this function. That's the stability guarantee the test suite asks+ * for.+ */+export function appendLogEvent(+ vault: string,+ event: BrainLogEntry,+): AppendLogEventResult {+ if (!EVENT_KIND_VALUES.has(event.eventType)) {+ throw new Error(+ `appendLogEvent: unknown event kind '${event.eventType}' β must be one of ${Object.values(+ BRAIN_LOG_EVENT_KIND,+ ).join(", ")}`,+ );+ }+ // Parse the timestamp once to extract date + HHMMSS deterministically.+ // We deliberately do not accept Date objects: the caller controls the+ // canonical representation so two calls with identical input produce+ // byte-identical output (idempotency requirement).+ const ts = parseIsoUtc(event.timestamp);+ const path = logPath(vault, ts.date);++ const existing = existsSync(path) ? readFileSync(path, "utf8") : "";+ const block = renderEventBlock(event, ts.hms);++ let next: string;+ if (existing === "") {+ next = renderFileHeader(ts.date) + "\n" + block;+ } else {+ // Guarantee exactly one blank line between blocks; previous file may+ // or may not end with a trailing newline.+ const trimmed = existing.replace(/\s+$/, "");+ next = `${trimmed}\n\n${block}`;+ }+ // Always finish with a single trailing newline β standard Markdown+ // hygiene, and matches what `formatFrontmatter` emits elsewhere.+ if (!next.endsWith("\n")) next += "\n";++ atomicWriteFileSync(path, next);+ return { logPath: path };+}++// ----- Renderers ------------------------------------------------------------++function renderFileHeader(date: string): string {+ // Frontmatter is hand-rendered (not via `formatFrontmatter`) because+ // the tags array must be a stable, comma-separated inline list, and+ // we need byte-deterministic output for the test suite.+ const lines: string[] = [+ "---",+ "kind: brain-log",+ `date: ${date}`,+ "tags: [brain, brain/log]",+ "---",+ "",+ `# Brain log β ${date}`,+ ];+ return lines.join("\n") + "\n";+}++function renderEventBlock(event: BrainLogEntry, hms: string): string {+ const lines: string[] = [`## ${hms}Z β ${event.eventType}`];+ // Stable iteration order: keys in the order they appear in the+ // payload object. The caller is responsible for the order they care+ // about; we don't sort because some events benefit from a logical+ // grouping (e.g. `run_id` first).+ for (const [key, value] of Object.entries(event.body)) {+ if (Array.isArray(value)) {+ // Repeated keys are encoded as a parent bullet with the bare key+ // followed by indented sub-bullets β matches the design-doc+ // example for `dream.new_unconfirmed`.+ lines.push(`- ${key}:`);+ for (const item of value) {+ lines.push(` - ${item}`);+ }+ } else {+ lines.push(`- ${key}: ${value}`);+ }+ }+ return lines.join("\n") + "\n";+}++// ----- Bullet block parser --------------------------------------------------++interface ParseBulletResult {+ readonly payload: Record<string, string | ReadonlyArray<string>>;+ readonly blockWarnings: ReadonlyArray<BrainLogParseWarning>;+}++function parseBulletBlock(+ lines: ReadonlyArray<string>,+ startLineNumber: number,+ path: string,+): ParseBulletResult {+ const payload: Record<string, string | ReadonlyArray<string>> = {};+ const blockWarnings: BrainLogParseWarning[] = [];++ // We walk the block linearly. Top-level bullets either carry their+ // value inline (`- key: value`) or open a sub-bullet list (`- key:`+ // followed by ` - <item>` lines). We close the current sub-list as+ // soon as we hit either another top-level bullet or a blank line.+ let cursor = 0;+ let currentListKey: string | null = null;+ let currentList: string[] | null = null;++ const flushList = (): void => {+ if (currentListKey !== null && currentList !== null) {+ payload[currentListKey] = currentList;+ }+ currentListKey = null;+ currentList = null;+ };++ while (cursor < lines.length) {+ const raw = lines[cursor]!;+ const lineNumber = startLineNumber + cursor;+ const trimmed = raw.trim();+ if (trimmed === "") {+ flushList();+ cursor++;+ continue;+ }+ const sub = SUB_BULLET_RE.exec(raw);+ if (sub && currentList !== null) {+ currentList.push(sub[1]!.trim());+ cursor++;+ continue;+ }+ const bullet = BULLET_RE.exec(raw);+ if (!bullet) {+ blockWarnings.push({+ path,+ lineNumber,+ message: `malformed bullet: ${raw}`,+ });+ flushList();+ cursor++;+ continue;+ }+ flushList();+ const key = bullet[1]!;+ const value = bullet[2]!;+ if (value === "") {+ currentListKey = key;+ currentList = [];+ } else {+ payload[key] = value;+ }+ cursor++;+ }+ flushList();+ return { payload, blockWarnings };+}++// ----- Time utilities ------------------------------------------------------++interface IsoUtcParts {+ readonly date: string;+ readonly hms: string;+}++/**+ * Parse an ISO-8601 UTC timestamp into its date and `HH:MM:SS` parts.+ * Accepts both `2026-05-14T10:42:00Z` and `2026-05-14T10:42:00.123Z`+ * forms; sub-second precision is truncated to seconds because the log+ * heading shape is `HH:MM:SS` only.+ */+function parseIsoUtc(timestamp: string): IsoUtcParts {+ const m =+ /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?Z$/.exec(+ timestamp,+ );+ if (!m) {+ throw new Error(+ `appendLogEvent: timestamp must be ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ); got ${JSON.stringify(timestamp)}`,+ );+ }+ return { date: m[1]!, hms: `${m[2]!}:${m[3]!}:${m[4]!}` };+}diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.tsnew file mode 100644index 00000000..7ccb20c6--- /dev/null+++ b/src/core/brain/paths.ts@@ -0,0 +1,308 @@+/**+ * Filesystem paths and slug allocation for the Brain layer.+ *+ * Layout lives under `<vault>/Brain/`:+ *+ * Brain/+ * _brain.yaml+ * inbox/+ * sig-<date>-<slug>.md+ * processed/sig-<date>-<slug>.md+ * preferences/+ * pref-<slug>.md+ * retired/+ * ret-<slug>.md+ * log/+ * <YYYY-MM-DD>.md+ * .snapshots/+ * <run_id>.tar.zst+ *+ * Every constructor here funnels through `ensureInsideVault` (re-exported+ * from `../path-safety`) so a malformed slug or a `..` traversal cannot+ * land a file outside the vault root. Slug validation rejects empties,+ * path separators, traversal sequences, and Windows-reserved basenames+ * β same contract as the Pay Memory layer.+ */++import { existsSync } from "node:fs";+import { join } from "node:path";++import { ensureInsideVault, vaultRelative } from "../path-safety.ts";++export { ensureInsideVault, vaultRelative } from "../path-safety.ts";++const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;++// Run IDs follow `dream-<YYYY-MM-DD>-<HHMMSS>`; we accept the same generic+// "no path separators / no traversal" rules as slugs, plus a tighter+// shape check for the date-time stem.+const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;++const WINDOWS_RESERVED_BASENAME_RE =+ /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;++export interface BrainDirs {+ readonly brain: string;+ readonly inbox: string;+ /** Holding area for signals already folded into a preference. */+ readonly processed: string;+ readonly preferences: string;+ readonly retired: string;+ readonly log: string;+ /** Pre-`dream` archive directory. Never recursed into by `dream`. */+ readonly snapshots: string;+}++/**+ * Compose every Brain subdirectory under `<vault>/Brain/`. Returns+ * absolute paths so callers can hand them straight to `mkdirSync` /+ * `readdirSync`. Each path is verified to resolve inside the vault.+ */+export function brainDirs(vault: string): BrainDirs {+ const brain = ensureInsideVault(join(vault, "Brain"), vault);+ return {+ brain,+ inbox: ensureInsideVault(join(brain, "inbox"), vault),+ processed: ensureInsideVault(join(brain, "inbox", "processed"), vault),+ preferences: ensureInsideVault(join(brain, "preferences"), vault),+ retired: ensureInsideVault(join(brain, "retired"), vault),+ log: ensureInsideVault(join(brain, "log"), vault),+ snapshots: ensureInsideVault(join(brain, ".snapshots"), vault),+ };+}++/** Path of `Brain/_brain.yaml`. */+export function brainConfigPath(vault: string): string {+ return ensureInsideVault(join(brainDirs(vault).brain, "_brain.yaml"), vault);+}++/** Path of the Brain operating manual rendered into the vault. */+export function brainManualPath(vault: string): string {+ return ensureInsideVault(join(brainDirs(vault).brain, "_BRAIN.md"), vault);+}++/** Active-signal path: `Brain/inbox/sig-<date>-<slug>.md`. */+export function signalPath(vault: string, date: string, slug: string): string {+ const d = validateIsoDate(date);+ const s = validateSlug(slug);+ return ensureInsideVault(+ join(brainDirs(vault).inbox, `sig-${d}-${s}.md`),+ vault,+ );+}++/** Processed-signal path: `Brain/inbox/processed/sig-<date>-<slug>.md`. */+export function processedSignalPath(+ vault: string,+ date: string,+ slug: string,+): string {+ const d = validateIsoDate(date);+ const s = validateSlug(slug);+ return ensureInsideVault(+ join(brainDirs(vault).processed, `sig-${d}-${s}.md`),+ vault,+ );+}++/** Preference path: `Brain/preferences/pref-<slug>.md`. */+export function preferencePath(vault: string, slug: string): string {+ const s = validateSlug(slug);+ return ensureInsideVault(+ join(brainDirs(vault).preferences, `pref-${s}.md`),+ vault,+ );+}++/** Retired-preference path: `Brain/retired/ret-<slug>.md`. */+export function retiredPath(vault: string, slug: string): string {+ const s = validateSlug(slug);+ return ensureInsideVault(+ join(brainDirs(vault).retired, `ret-${s}.md`),+ vault,+ );+}++/** Log file for the given UTC date: `Brain/log/<YYYY-MM-DD>.md`. */+export function logPath(vault: string, date: string): string {+ const d = validateIsoDate(date);+ return ensureInsideVault(join(brainDirs(vault).log, `${d}.md`), vault);+}++/** Snapshots directory: `Brain/.snapshots/`. */+export function snapshotsDir(vault: string): string {+ return brainDirs(vault).snapshots;+}++/** Snapshot archive path: `Brain/.snapshots/<run_id>.tar.zst`. */+export function snapshotPath(vault: string, runId: string): string {+ const id = validateRunId(runId);+ return ensureInsideVault(+ join(brainDirs(vault).snapshots, `${id}.tar.zst`),+ vault,+ );+}++// ----- Validators -----------------------------------------------------------++/**+ * Reject slugs that could escape their intended subdirectory or hit a+ * Windows-incompatible filename. Same shape rules as Pay Memory's+ * `validateSlug`, copied here to avoid coupling the two layers.+ */+export function validateSlug(slug: string): string {+ const trimmed = slug.trim();+ if (!trimmed) throw new Error("slug must not be empty");+ if (trimmed.includes("/") || trimmed.includes("\\")) {+ throw new Error(`slug must not contain path separators: ${slug}`);+ }+ // Reject Windows-invalid filename characters (`:*?"<>|`) and ASCII+ // control characters (0x00-0x1F). On NTFS these are forbidden in a+ // filename; on POSIX a NUL byte is illegal in a path and the rest are+ // ambiguous when round-tripped through cross-platform tooling (zip+ // archives, syncthing, git on Windows).+ if (/[:*?"<>|\x00-\x1F]/.test(trimmed)) {+ throw new Error(+ `slug contains invalid character: ${JSON.stringify(slug)}`,+ );+ }+ if (+ trimmed === ".." ||+ trimmed === "." ||+ /(?:^|[^\w])\.\.(?:$|[^\w])/.test(trimmed)+ ) {+ throw new Error(`slug must not contain '..' traversal: ${slug}`);+ }+ if (/[. ]$/.test(trimmed)) {+ throw new Error(+ `slug must not end with '.' or whitespace (Windows-incompatible): ${slug}`,+ );+ }+ if (WINDOWS_RESERVED_BASENAME_RE.test(trimmed)) {+ throw new Error(`slug uses a Windows-reserved filename: ${slug}`);+ }+ return trimmed;+}++/** Validate `YYYY-MM-DD`. Throws on bad shape or impossible calendar date. */+export function validateIsoDate(value: string): string {+ const m = ISO_DATE_RE.exec(value);+ if (!m) {+ throw new Error(`brain date must use YYYY-MM-DD format: ${value}`);+ }+ const year = parseInt(m[1]!, 10);+ const month = parseInt(m[2]!, 10);+ const day = parseInt(m[3]!, 10);+ const utc = new Date(Date.UTC(year, month - 1, day));+ if (+ utc.getUTCFullYear() !== year ||+ utc.getUTCMonth() !== month - 1 ||+ utc.getUTCDate() !== day+ ) {+ throw new Error(`brain date is not a valid calendar date: ${value}`);+ }+ return value;+}++/**+ * Validate a snapshot run_id. The dream algorithm forms run_ids as+ * `dream-<YYYY-MM-DD>-<HHMMSS>`; the validator is intentionally+ * permissive about the exact stem (we want manual snapshots later) and+ * focuses on filesystem-safety: no separators, no traversal, no Windows+ * reservation, no leading dot.+ */+export function validateRunId(runId: string): string {+ const trimmed = runId.trim();+ if (!trimmed) throw new Error("run_id must not be empty");+ if (!RUN_ID_RE.test(trimmed)) {+ throw new Error(+ `run_id must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/: ${runId}`,+ );+ }+ if (+ trimmed.includes("..") ||+ trimmed.includes("/") ||+ trimmed.includes("\\")+ ) {+ throw new Error(`run_id must not contain '..' or path separators: ${runId}`);+ }+ if (WINDOWS_RESERVED_BASENAME_RE.test(trimmed)) {+ throw new Error(`run_id uses a Windows-reserved filename: ${runId}`);+ }+ return trimmed;+}++// ----- Slug-collision allocator --------------------------------------------++export interface AllocateSlugOptions {+ /** Vault root. Required so collision probes stay inside the vault. */+ readonly vault: string;+ /** Directory the file will live in (absolute). */+ readonly targetDir: string;+ /** File-name prefix without trailing dash, e.g. `sig-2026-05-14`. */+ readonly prefix: string;+ /** Base slug requested by the caller. */+ readonly slug: string;+ /**+ * Hard upper bound on suffix attempts. The default of 10_000 is far+ * beyond any realistic same-day collision count and exists only to+ * make a misuse error (caller passing a `targetDir` that resolves+ * outside the vault, say) terminate instead of loop forever.+ */+ readonly maxAttempts?: number;+}++export interface AllocateSlugResult {+ /** Allocated slug ready to be combined with the prefix. */+ readonly slug: string;+ /** Final absolute filename (`<targetDir>/<prefix>-<slug>.md`). */+ readonly path: string;+ /** Suffix that was appended (`null` when no collision). */+ readonly suffix: number | null;+}++/**+ * Find the first free `<prefix>-<slug>.md` under `targetDir`, appending+ * `-2`, `-3`, β¦ to the slug on collision. The probe is read-only β+ * callers create the file themselves via the atomic-exclusive writer+ * (which closes the residual TOCTOU window).+ *+ * Returns the chosen slug + the absolute path. The path is funnelled+ * through `ensureInsideVault` so a misconfigured `targetDir` (e.g. one+ * the caller assembled by hand and that points outside the vault)+ * raises before any disk probe is made.+ */+export function allocateSlug(opts: AllocateSlugOptions): AllocateSlugResult {+ const { vault, targetDir, prefix } = opts;+ const baseSlug = validateSlug(opts.slug);+ const maxAttempts = opts.maxAttempts ?? 10_000;++ if (!prefix || /[\\/]/.test(prefix)) {+ throw new Error(`allocateSlug: prefix must be non-empty and path-clean: ${prefix}`);+ }++ // The first candidate is the bare slug. Subsequent attempts append+ // `-2`, `-3`, β¦ per Β§5.1 / Β§9.2 of the design doc. Cap at+ // `maxAttempts` to prevent an unbounded loop when the caller passes+ // a target directory containing infinite collisions (e.g. on a fuzz+ // test); the realistic worst case is a handful.+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {+ const slug = attempt === 1 ? baseSlug : `${baseSlug}-${attempt}`;+ const candidate = ensureInsideVault(+ join(targetDir, `${prefix}-${slug}.md`),+ vault,+ );+ if (!existsSync(candidate)) {+ return { slug, path: candidate, suffix: attempt === 1 ? null : attempt };+ }+ }+ throw new Error(+ `allocateSlug: could not find a free name after ${maxAttempts} attempts ` ++ `(prefix=${prefix}, slug=${baseSlug})`,+ );+}++/** Vault-relative renderer kept here for the `tests/core/brain.paths.test.ts` import. */+export function brainVaultRelative(target: string, vault: string): string {+ return vaultRelative(target, vault);+}diff --git a/src/core/brain/pin.ts b/src/core/brain/pin.tsnew file mode 100644index 00000000..d98b3a9b--- /dev/null+++ b/src/core/brain/pin.ts@@ -0,0 +1,143 @@+/**+ * Pin / unpin operations.+ *+ * A pinned preference is exempt from the three automatic retire reasons+ * (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`). Pinning is a+ * CLI-only operation β the MCP surface deliberately does NOT expose it+ * so autonomous agents cannot mutate the protected set (design doc+ * Β§7.4, Β§15 Step 9b).+ *+ * Surface:+ *+ * - {@link setPinned} flips a single preference's `pinned` boolean+ * atomically. The frontmatter is rewritten through+ * `writeFrontmatterAtomic` with `overwrite: true`. The body bytes+ * of the preference are preserved verbatim β we only touch the+ * frontmatter. The function is idempotent: a no-op flip returns+ * `changed: false` and writes nothing.+ *+ * - {@link isPinned} is the trivial accessor with a default of+ * `false`. The parser in `preference.ts` already coerces missing+ * frontmatter values to `false`, but we keep this helper for+ * callers (notably `dream`) that want to express intent without+ * reaching into the `BrainPreference` shape directly.+ *+ * A successful flip emits a `pin` or `unpin` log event via+ * `appendLogEvent`. A no-op (`changed: false`) emits no log entry β the+ * log is reserved for state transitions, not redundant calls.+ */++import { existsSync } from "node:fs";++import { writeFrontmatterAtomic, parseFrontmatter } from "../vault.ts";+import { appendLogEvent, type BrainLogEntry } from "./log.ts";+import { parsePreference } from "./preference.ts";+import { preferencePath, validateSlug } from "./paths.ts";+import { isoSecond } from "./time.ts";+import { BRAIN_LOG_EVENT_KIND, type BrainPreference } from "./types.ts";+import { BrainPreferenceNotFoundError } from "./apply-evidence.ts";++export interface SetPinnedOptions {+ /** Override the wall clock used in the log event. */+ readonly now?: Date;+ /**+ * Source agent recorded as a payload field on the log event. Defaults+ * to `"cli"` to reflect that pinning is a CLI-only operation; the+ * CLI passes the resolved `AGENT_NAME`. The MCP surface never reaches+ * this code path (Brain MCP tools do not expose pin/unpin).+ */+ readonly agent?: string;+}++export interface SetPinnedResult {+ /** Absolute path of the preference file. */+ readonly path: string;+ /**+ * `true` if the on-disk value transitioned (false β true or+ * true β false). `false` when the requested state was already set β+ * the call is a no-op and no log entry was written.+ */+ readonly changed: boolean;+}++/**+ * Flip a preference's `pinned` frontmatter field. Atomic and+ * idempotent.+ *+ * @throws {@link BrainPreferenceNotFoundError} when the preference does+ * not resolve to a file under `Brain/preferences/`. We reuse the+ * `apply-evidence` error class so CLI surface treats both+ * "wrong pref_id" cases consistently.+ */+export function setPinned(+ vault: string,+ prefId: string,+ value: boolean,+ opts: SetPinnedOptions = {},+): SetPinnedResult {+ if (typeof prefId !== "string" || !prefId.trim()) {+ throw new Error("setPinned missing field: pref_id");+ }+ if (typeof value !== "boolean") {+ throw new Error(+ `setPinned: 'value' must be a boolean; got ${JSON.stringify(value)}`,+ );+ }++ const trimmed = prefId.trim();+ const slug = trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;+ if (!slug) {+ throw new Error(`setPinned: invalid pref_id (empty slug): ${prefId}`);+ }+ validateSlug(slug);+ const path = preferencePath(vault, slug);+ if (!existsSync(path)) {+ throw new BrainPreferenceNotFoundError(`pref-${slug}`, path);+ }++ // Re-parse the file to drive the idempotency check off the canonical+ // boolean (rather than the raw frontmatter string), and to validate+ // the file's shape before we rewrite it. A corrupt preference here+ // is a hard error β the caller asked us to mutate a specific rule;+ // we refuse to make that decision blindly.+ const current = parsePreference(path);+ if (current.pinned === value) {+ return { path, changed: false };+ }++ // Read the raw frontmatter + body so we can rewrite without+ // disturbing the human-authored prose ("## Principle", "## Origin",+ // "## How to apply", and any custom sections appended downstream).+ const [meta, body] = parseFrontmatter(path);+ const newMeta = { ...meta, pinned: value };+ writeFrontmatterAtomic(path, newMeta, body, {+ overwrite: true,+ existsErrorKind: "preference",+ vaultForRelativePath: vault,+ });++ // Emit the log event only on a real transition.+ const now = opts.now ?? new Date();+ const entry: BrainLogEntry = {+ timestamp: isoSecond(now),+ eventType: value ? BRAIN_LOG_EVENT_KIND.pin : BRAIN_LOG_EVENT_KIND.unpin,+ body: {+ preference: `[[pref-${slug}]]`,+ agent: (opts.agent ?? "cli").trim() || "cli",+ },+ };+ appendLogEvent(vault, entry);++ return { path, changed: true };+}++/**+ * Read the `pinned` boolean off a parsed preference, defaulting to+ * `false`. The parser already coerces missing/null values, so this is+ * a trivial accessor β but having it as a named helper keeps `dream`'s+ * pin-skip branches readable.+ */+export function isPinned(pref: BrainPreference): boolean {+ return pref.pinned === true;+}+diff --git a/src/core/brain/policy.ts b/src/core/brain/policy.tsnew file mode 100644index 00000000..583b71cc--- /dev/null+++ b/src/core/brain/policy.ts@@ -0,0 +1,552 @@+/**+ * Brain configuration loader and validator (`Brain/_brain.yaml`).+ *+ * The Brain config is nested two levels deep (top-level keys, each+ * containing a flat `key: number` block) β too rich for the+ * `parseSimpleYaml` flat parser used by the plugin config, but a far cry+ * from needing a real YAML library. We ship a tiny indent-aware parser+ * limited to:+ *+ * - `# comments` and blank lines+ * - `key: <scalar>` (numbers parsed; quoted strings stripped)+ * - `key:` followed by an indented block of the same form (one level)+ *+ * Anything else is treated as invalid and surfaces through+ * `validateBrainConfig` with a field-named error. No external+ * dependency, no eval, no surprise.+ *+ * Anchored in design doc Β§10.+ */++import { existsSync, readFileSync } from "node:fs";++import type { BrainConfig } from "./types.ts";+import { brainConfigPath } from "./paths.ts";++/** Schema versions this build understands. Bump on incompatible changes. */+export const BRAIN_CONFIG_SUPPORTED_VERSIONS: ReadonlyArray<number> = [1];++/**+ * Default `_brain.yaml` content. Mirrors Β§10 of the design doc. Used by+ * `brain init` and as the fallback inside `loadBrainConfig` when callers+ * opt into permissive mode (the current API is strict β absent file+ * throws).+ */+export const DEFAULT_BRAIN_CONFIG: BrainConfig = Object.freeze({+ schema_version: 1,+ dream: Object.freeze({+ candidate_threshold: 3,+ unconfirmed_window_days: 14,+ contradiction_window_days: 14,+ }),+ retire: Object.freeze({+ stale_evidence_days: 90,+ }),+ confidence: Object.freeze({+ low_max_applied: 2,+ high_min_applied: 10,+ high_freshness_factor: 0.8,+ }),+ snapshots: Object.freeze({+ retention_count: 10,+ }),+}) as BrainConfig;++/**+ * Serialised default `_brain.yaml`. Hand-formatted to match the design+ * doc verbatim β `brain init` writes this byte string so the file the+ * user sees is the file the docs describe.+ */+export const DEFAULT_BRAIN_CONFIG_YAML = `schema_version: 1++dream:+ candidate_threshold: 3+ unconfirmed_window_days: 14+ contradiction_window_days: 14++retire:+ stale_evidence_days: 90++confidence:+ low_max_applied: 2+ high_min_applied: 10+ high_freshness_factor: 0.8++snapshots:+ retention_count: 10+`;++/**+ * Warnings collected during validation. Forward-compat tolerates unknown+ * top-level keys but surfaces them so a typo doesn't go unnoticed.+ */+export interface BrainConfigLoadWarning {+ readonly path: string;+ readonly message: string;+}++export class BrainConfigError extends Error {+ /**+ * Dotted field path that caused the failure (`dream.candidate_threshold`,+ * `schema_version`, β¦). `null` for top-level type errors.+ */+ readonly field: string | null;+ readonly source: string | null;++ constructor(message: string, field: string | null, source: string | null) {+ super(field ? `${source ?? "<config>"}: ${field}: ${message}` : `${source ?? "<config>"}: ${message}`);+ this.name = "BrainConfigError";+ this.field = field;+ this.source = source;+ }+}++// ----- Public API -----------------------------------------------------------++export interface LoadBrainConfigResult {+ readonly config: BrainConfig;+ readonly warnings: ReadonlyArray<BrainConfigLoadWarning>;+ readonly path: string;+}++/**+ * Read and validate `<vault>/Brain/_brain.yaml`.+ *+ * Throws {@link BrainConfigError} on:+ * - missing file+ * - YAML shape errors+ * - unsupported `schema_version`+ * - non-integer / out-of-range thresholds+ * - `high_freshness_factor` outside `(0, 1]`+ * - non-integer / non-positive `snapshots.retention_count`+ *+ * Unknown top-level keys are reported as warnings, not errors.+ */+export function loadBrainConfig(vault: string): BrainConfig {+ return loadBrainConfigDetailed(vault).config;+}++/**+ * Same as {@link loadBrainConfig} but also returns parser warnings (for+ * the future `o2b brain doctor` integration).+ */+export function loadBrainConfigDetailed(vault: string): LoadBrainConfigResult {+ const path = brainConfigPath(vault);+ if (!existsSync(path)) {+ throw new BrainConfigError(+ "config file does not exist; run `o2b brain init` first",+ null,+ path,+ );+ }+ let text: string;+ try {+ text = readFileSync(path, "utf8");+ } catch (err) {+ throw new BrainConfigError(+ `failed to read: ${(err as Error).message ?? String(err)}`,+ null,+ path,+ );+ }++ let parsed: ParsedBlock;+ try {+ parsed = parseBrainYaml(text);+ } catch (err) {+ throw new BrainConfigError(+ (err as Error).message,+ null,+ path,+ );+ }++ const { config, warnings } = validateBrainConfigDetailed(parsed, path);+ return { config, warnings, path };+}++/**+ * Pure validator. Accepts a parsed object (typically from+ * {@link parseBrainYaml}) and returns a typed {@link BrainConfig}, or+ * throws {@link BrainConfigError} naming the offending field.+ *+ * `source` is rendered into error messages; pass the config file path or+ * a synthetic label like `"<test fixture>"` so the failure points at+ * something useful.+ */+export function validateBrainConfig(+ parsed: unknown,+ source: string | null = null,+): BrainConfig {+ return validateBrainConfigDetailed(parsed, source).config;+}++export interface ValidateResult {+ readonly config: BrainConfig;+ readonly warnings: ReadonlyArray<BrainConfigLoadWarning>;+}++export function validateBrainConfigDetailed(+ parsed: unknown,+ source: string | null = null,+): ValidateResult {+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {+ throw new BrainConfigError("config root must be a map of keys", null, source);+ }+ const obj = parsed as Record<string, unknown>;+ const warnings: BrainConfigLoadWarning[] = [];++ // schema_version is mandatory and must be in the supported set.+ if (!("schema_version" in obj)) {+ throw new BrainConfigError(+ "missing required field; expected a positive integer in the supported set " ++ `(${BRAIN_CONFIG_SUPPORTED_VERSIONS.join(", ")})`,+ "schema_version",+ source,+ );+ }+ const schemaVersion = obj["schema_version"];+ if (+ typeof schemaVersion !== "number" ||+ !Number.isInteger(schemaVersion) ||+ !BRAIN_CONFIG_SUPPORTED_VERSIONS.includes(schemaVersion)+ ) {+ throw new BrainConfigError(+ `unsupported value ${JSON.stringify(schemaVersion)}; expected one of ` ++ BRAIN_CONFIG_SUPPORTED_VERSIONS.join(", "),+ "schema_version",+ source,+ );+ }++ // Each block is optional; missing blocks inherit the default. We+ // merge field-by-field so a user can override one threshold without+ // having to re-state the rest.+ const dream = mergeBlock(+ "dream",+ obj["dream"],+ DEFAULT_BRAIN_CONFIG.dream as unknown as Readonly<Record<string, number>>,+ source,+ );+ requirePositiveInteger("dream.candidate_threshold", dream.candidate_threshold, source);+ requirePositiveInteger("dream.unconfirmed_window_days", dream.unconfirmed_window_days, source);+ requirePositiveInteger("dream.contradiction_window_days", dream.contradiction_window_days, source);++ const retire = mergeBlock(+ "retire",+ obj["retire"],+ DEFAULT_BRAIN_CONFIG.retire as unknown as Readonly<Record<string, number>>,+ source,+ );+ requirePositiveInteger("retire.stale_evidence_days", retire.stale_evidence_days, source);++ const confidence = mergeBlock(+ "confidence",+ obj["confidence"],+ DEFAULT_BRAIN_CONFIG.confidence as unknown as Readonly<Record<string, number>>,+ source,+ );+ requireNonNegativeInteger(+ "confidence.low_max_applied",+ confidence.low_max_applied,+ source,+ );+ requirePositiveInteger(+ "confidence.high_min_applied",+ confidence.high_min_applied,+ source,+ );+ if (+ typeof confidence.high_freshness_factor !== "number" ||+ !Number.isFinite(confidence.high_freshness_factor) ||+ confidence.high_freshness_factor <= 0 ||+ confidence.high_freshness_factor > 1+ ) {+ throw new BrainConfigError(+ `must be a number in (0, 1]; got ${JSON.stringify(confidence.high_freshness_factor)}`,+ "confidence.high_freshness_factor",+ source,+ );+ }++ const snapshots = mergeBlock(+ "snapshots",+ obj["snapshots"],+ DEFAULT_BRAIN_CONFIG.snapshots as unknown as Readonly<Record<string, number>>,+ source,+ );+ requirePositiveInteger("snapshots.retention_count", snapshots.retention_count, source);++ // Forward-compat: unknown top-level keys β warning, not error.+ const known = new Set([+ "schema_version",+ "dream",+ "retire",+ "confidence",+ "snapshots",+ ]);+ for (const key of Object.keys(obj)) {+ if (!known.has(key)) {+ warnings.push({+ path: source ?? "<config>",+ message: `unknown top-level field '${key}' ignored (forward-compat)`,+ });+ }+ }++ const config: BrainConfig = {+ schema_version: schemaVersion,+ dream: {+ candidate_threshold: dream.candidate_threshold as number,+ unconfirmed_window_days: dream.unconfirmed_window_days as number,+ contradiction_window_days: dream.contradiction_window_days as number,+ },+ retire: {+ stale_evidence_days: retire.stale_evidence_days as number,+ },+ confidence: {+ low_max_applied: confidence.low_max_applied as number,+ high_min_applied: confidence.high_min_applied as number,+ high_freshness_factor: confidence.high_freshness_factor as number,+ },+ snapshots: {+ retention_count: snapshots.retention_count as number,+ },+ };++ return { config, warnings };+}++// ----- Helpers --------------------------------------------------------------++/**+ * Merge a parsed block (or `undefined`) with its default, returning a+ * plain object whose value types are validated downstream. A non-object+ * block (string, number, array) is a hard error β the user probably+ * miswrote the YAML.+ */+function mergeBlock(+ blockKey: string,+ raw: unknown,+ fallback: Readonly<Record<string, number>>,+ source: string | null,+): Record<string, unknown> {+ if (raw === undefined) {+ return { ...fallback };+ }+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {+ throw new BrainConfigError(+ `block must be a map of keys; got ${describe(raw)}`,+ blockKey,+ source,+ );+ }+ const merged: Record<string, unknown> = { ...fallback };+ for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {+ merged[k] = v;+ }+ return merged;+}++function requirePositiveInteger(+ field: string,+ value: unknown,+ source: string | null,+): void {+ if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {+ throw new BrainConfigError(+ `must be a positive integer; got ${describe(value)}`,+ field,+ source,+ );+ }+}++function requireNonNegativeInteger(+ field: string,+ value: unknown,+ source: string | null,+): void {+ if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {+ throw new BrainConfigError(+ `must be a non-negative integer; got ${describe(value)}`,+ field,+ source,+ );+ }+}++function describe(value: unknown): string {+ if (value === null) return "null";+ if (value === undefined) return "undefined";+ if (Array.isArray(value)) return `array(${value.length})`;+ if (typeof value === "object") return "object";+ return `${typeof value}(${JSON.stringify(value)})`;+}++// ----- Minimal indent-aware YAML parser ------------------------------------+//+// The parser handles only the shape used by `_brain.yaml`:+//+// - `# comment` lines and blanks+// - top-level `key: <scalar>`+// - top-level `key:` followed by an indented block of one indent level+// - block-level `<indent>key: <scalar>`+//+// Scalars are parsed as:+// - plain integers / floats (no exponents, no leading +)+// - quoted strings ('..' or "..") β the quotes are stripped and the+// content is taken as-is (no escape sequences)+// - the bare words `true`, `false`, `null`+// - otherwise: the literal string+//+// This intentionally rejects nested mappings deeper than two levels,+// inline arrays, anchors, and aliases β none of which the schema needs.++type ParsedScalar = number | string | boolean | null;+type ParsedBlock = Record<string, ParsedScalar | Record<string, ParsedScalar>>;++interface Line {+ readonly raw: string;+ readonly indent: number;+ readonly content: string;+ readonly lineNumber: number;+}++export function parseBrainYaml(text: string): ParsedBlock {+ const lines = splitLines(text);+ const out: ParsedBlock = {};+ let i = 0;+ while (i < lines.length) {+ const line = lines[i]!;+ if (line.indent !== 0) {+ throw new Error(+ `line ${line.lineNumber}: unexpected indentation at top level`,+ );+ }+ const kv = splitKeyValue(line);+ if (kv.value === "") {+ // Block header: collect indented children.+ const child: Record<string, ParsedScalar> = {};+ i++;+ const blockIndent = detectBlockIndent(lines, i);+ while (i < lines.length && lines[i]!.indent >= blockIndent && blockIndent > 0) {+ const inner = lines[i]!;+ if (inner.indent !== blockIndent) {+ throw new Error(+ `line ${inner.lineNumber}: inconsistent indentation in block '${kv.key}' ` ++ `(expected ${blockIndent} spaces, got ${inner.indent})`,+ );+ }+ const innerKv = splitKeyValue(inner);+ if (innerKv.value === "") {+ throw new Error(+ `line ${inner.lineNumber}: nested blocks deeper than one level are not supported`,+ );+ }+ if (innerKv.key in child) {+ throw new Error(+ `line ${inner.lineNumber}: duplicate key '${innerKv.key}' in block '${kv.key}'`,+ );+ }+ child[innerKv.key] = parseScalar(innerKv.value, inner.lineNumber);+ i++;+ }+ if (kv.key in out) {+ throw new Error(`duplicate top-level key '${kv.key}'`);+ }+ out[kv.key] = child;+ continue;+ }+ if (kv.key in out) {+ throw new Error(`duplicate top-level key '${kv.key}'`);+ }+ out[kv.key] = parseScalar(kv.value, line.lineNumber);+ i++;+ }+ return out;+}++function splitLines(text: string): Line[] {+ const out: Line[] = [];+ let lineNumber = 0;+ for (const raw of text.split(/\r?\n/)) {+ lineNumber++;+ // Strip trailing whitespace; leave leading intact for indent detection.+ const stripped = raw.replace(/\s+$/, "");+ // Skip blanks and comment-only lines.+ if (stripped.trim() === "") continue;+ if (stripped.trimStart().startsWith("#")) continue;+ // Strip inline comments only when they are clearly outside a quoted+ // value. Keep this simple: only honour ` #` (space then hash) on+ // unquoted lines. Quoted values keep their content verbatim.+ let content = stripped;+ if (!/['"]/.test(stripped)) {+ const hashIdx = stripped.indexOf(" #");+ if (hashIdx >= 0) content = stripped.slice(0, hashIdx).replace(/\s+$/, "");+ }+ const indent = content.length - content.trimStart().length;+ out.push({+ raw,+ indent,+ content: content.slice(indent),+ lineNumber,+ });+ }+ return out;+}++interface KeyValue {+ readonly key: string;+ readonly value: string;+}++function splitKeyValue(line: Line): KeyValue {+ const idx = line.content.indexOf(":");+ if (idx <= 0) {+ throw new Error(+ `line ${line.lineNumber}: expected 'key: value', got: ${JSON.stringify(line.raw)}`,+ );+ }+ const key = line.content.slice(0, idx).trim();+ if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) {+ throw new Error(+ `line ${line.lineNumber}: invalid key name: ${JSON.stringify(key)}`,+ );+ }+ const value = line.content.slice(idx + 1).trim();+ return { key, value };+}++function detectBlockIndent(lines: Line[], cursor: number): number {+ if (cursor >= lines.length) return 0;+ const first = lines[cursor]!;+ if (first.indent === 0) return 0; // empty block (next top-level key)+ return first.indent;+}++function parseScalar(text: string, lineNumber: number): ParsedScalar {+ if (+ text.length >= 2 &&+ ((text.startsWith('"') && text.endsWith('"')) ||+ (text.startsWith("'") && text.endsWith("'")))+ ) {+ return text.slice(1, -1);+ }+ if (text === "true") return true;+ if (text === "false") return false;+ if (text === "null" || text === "~") return null;+ // Number: integer or finite decimal. Anything else β literal string.+ if (/^-?\d+$/.test(text)) {+ const n = parseInt(text, 10);+ return n;+ }+ if (/^-?\d+\.\d+$/.test(text)) {+ const n = parseFloat(text);+ if (!Number.isFinite(n)) {+ throw new Error(`line ${lineNumber}: non-finite number: ${text}`);+ }+ return n;+ }+ return text;+}diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.tsnew file mode 100644index 00000000..c2638943--- /dev/null+++ b/src/core/brain/preference.ts@@ -0,0 +1,737 @@+/**+ * Preference (`pref-*.md`) and retired (`ret-*.md`) parsers, writer, and+ * the `preferences/ β retired/` mover.+ *+ * Preferences are rules promoted from clusters of signals (design doc+ * Β§5.3). They live in `Brain/preferences/` while active; they migrate+ * to `Brain/retired/` once they leave the loop, gaining retire metadata+ * but otherwise keeping the original slug β only the filename prefix+ * flips from `pref-` to `ret-`. The same identity slug is preserved+ * across the move so wikilinks pointing at `[[pref-foo]]` continue to+ * resolve (Obsidian indexes by basename regardless of folder, and the+ * retired file's frontmatter `id` flips to `ret-foo`).+ *+ * Three concerns matter:+ *+ * 1. **Default `pinned: false`** when parsing a file whose+ * frontmatter omits the field. The design doc Β§5.3 makes this+ * explicit; the type contract in `types.ts` says parsers MUST+ * coerce missing/null/undefined to `false`.+ *+ * 2. **Status-vs-folder invariant.** A file in `preferences/` whose+ * frontmatter `status` is `retired` (or a file in `retired/` whose+ * kind is `brain-preference`) is corrupt β almost certainly the+ * result of a half-completed move. Parsers throw+ * {@link BrainStatusFolderMismatchError} on read so the doctor+ * command (Task 4) can surface it as a warning. The parsers+ * themselves throw because the typed return value would otherwise+ * lie about the on-disk state.+ *+ * 3. **Atomic move.** `moveToRetired` performs the rename via two+ * atomic operations (write the new file, unlink the old) to keep+ * the filesystem consistent on a mid-run crash: the new file is+ * complete before the old one disappears.+ */++import { existsSync, unlinkSync } from "node:fs";+import { basename, dirname, join } from "node:path";++import type { FrontmatterMap } from "../types.ts";+import { writeFrontmatterAtomic, parseFrontmatter } from "../vault.ts";+import {+ brainDirs,+ preferencePath,+ retiredPath,+ validateSlug,+} from "./paths.ts";+import {+ BRAIN_CONFIDENCE,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_RETIRED_REASON,+ type BrainConfidence,+ type BrainPreference,+ type BrainPreferenceStatus,+ type BrainRetired,+ type BrainRetiredReason,+} from "./types.ts";++// ----- Errors ---------------------------------------------------------------++/**+ * Raised when a preference / retired file disagrees with the folder+ * it lives in. Surfaces both pieces of information so the caller (and+ * `o2b brain doctor`) can render an actionable message.+ */+export class BrainStatusFolderMismatchError extends Error {+ readonly path: string;+ readonly status: string;+ readonly folder: "preferences" | "retired";++ constructor(+ message: string,+ path: string,+ status: string,+ folder: "preferences" | "retired",+ ) {+ super(`${message} (path=${path}, status=${status}, folder=${folder})`);+ this.name = "BrainStatusFolderMismatchError";+ this.path = path;+ this.status = status;+ this.folder = folder;+ }+}++// ----- Writer inputs --------------------------------------------------------++export interface WritePreferenceInput {+ /** Slug stem (no `pref-` prefix). Used as the file basename. */+ readonly slug: string;+ readonly topic: string;+ readonly principle: string;+ readonly created_at: string;+ readonly unconfirmed_until: string;+ readonly status: BrainPreferenceStatus;+ readonly evidenced_by: ReadonlyArray<string>;+ readonly confirmed_at?: string | null;+ readonly scope?: string;+ readonly applied_count?: number;+ readonly violated_count?: number;+ readonly last_evidence_at?: string | null;+ readonly confidence?: BrainConfidence;+ readonly pinned?: boolean;+ readonly supersedes?: string;+ readonly aliases?: ReadonlyArray<string>;+ /** Optional extra tags merged after the canonical set. */+ readonly extraTags?: ReadonlyArray<string>;+ /** Free-form "How to apply" prose (rendered as a section). */+ readonly howToApply?: string;+}++export interface WritePreferenceOptions {+ /** When true, overwrite an existing file at the target path. */+ readonly overwrite?: boolean;+}++export interface WritePreferenceResult {+ readonly path: string;+ readonly id: string;+}++export interface MoveToRetiredOptions {+ readonly now: Date;+ readonly retired_by: string;+ readonly superseded_by?: string;+}++export interface MoveToRetiredResult {+ readonly path: string;+ readonly id: string;+}++// ----- Writer ---------------------------------------------------------------++/**+ * Write a preference atomically to `Brain/preferences/pref-<slug>.md`.+ *+ * The frontmatter snapshot includes every field on `BrainPreference`,+ * with safe defaults for the optional counters (zero) and confidence+ * (`low`). The body is the canonical three-section layout described in+ * Β§5.3 β "## Principle", "## Origin", "## How to apply".+ */+export function writePreference(+ vault: string,+ input: WritePreferenceInput,+ options: WritePreferenceOptions = {},+): WritePreferenceResult {+ if (!input.slug?.trim()) throw new Error("preference missing field: slug");+ if (!input.topic?.trim()) throw new Error("preference missing field: topic");+ if (!input.principle?.trim()) {+ throw new Error("preference missing field: principle");+ }+ if (!input.created_at?.trim()) {+ throw new Error("preference missing field: created_at");+ }+ if (!input.unconfirmed_until?.trim()) {+ throw new Error("preference missing field: unconfirmed_until");+ }+ if (+ input.status !== BRAIN_PREFERENCE_STATUS.unconfirmed &&+ input.status !== BRAIN_PREFERENCE_STATUS.confirmed+ ) {+ throw new Error(+ `preference field 'status' must be 'unconfirmed' or 'confirmed'; got ${JSON.stringify(input.status)}`,+ );+ }++ const slug = validateSlug(input.slug);+ const path = preferencePath(vault, slug);+ const id = `pref-${slug}`;++ const metadata = preferenceFrontmatter(input, id);+ const body = renderPreferenceBody(input);++ writeFrontmatterAtomic(path, metadata, body, {+ overwrite: options.overwrite ?? false,+ existsErrorKind: "preference",+ vaultForRelativePath: vault,+ });++ return { path, id };+}++function preferenceFrontmatter(+ input: WritePreferenceInput,+ id: string,+): FrontmatterMap {+ const tags = composePreferenceTags(input);+ const confidence = input.confidence ?? BRAIN_CONFIDENCE.low;+ const pinned = input.pinned ?? false;+ const applied = input.applied_count ?? 0;+ const violated = input.violated_count ?? 0;++ const metadata: FrontmatterMap = {+ kind: "brain-preference",+ id,+ created_at: input.created_at,+ // Use a textual sentinel for `null` so the simple parser surfaces+ // an empty string and the loader coerces back to `null`. We store+ // the literal text "null" rather than an empty value to keep the+ // emitted YAML one-token per line and the field always present.+ confirmed_at: input.confirmed_at ?? "null",+ unconfirmed_until: input.unconfirmed_until,+ tags: [...tags],+ topic: input.topic.trim(),+ status: input.status,+ principle: input.principle.trim(),+ evidenced_by: [...input.evidenced_by],+ applied_count: applied,+ violated_count: violated,+ last_evidence_at: input.last_evidence_at ?? "null",+ confidence,+ pinned,+ };+ 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) {+ metadata["aliases"] = [...input.aliases];+ }+ return metadata;+}++function composePreferenceTags(input: WritePreferenceInput): string[] {+ const out: string[] = [];+ const seen = new Set<string>();+ const push = (t: string): void => {+ if (!seen.has(t)) {+ seen.add(t);+ out.push(t);+ }+ };+ push("brain");+ push("brain/preference");+ push(`brain/topic/${input.topic.trim()}`);+ if (input.scope?.trim()) push(`brain/scope/${input.scope.trim()}`);+ for (const t of input.extraTags ?? []) {+ if (t.trim()) push(t.trim());+ }+ return out;+}++function renderPreferenceBody(input: WritePreferenceInput): string {+ const lines: string[] = [];+ lines.push("## Principle", "", input.principle.trim(), "");+ lines.push("## Origin", "");+ if (input.evidenced_by.length > 0) {+ for (const ev of input.evidenced_by) lines.push(`- ${ev}`);+ } else {+ lines.push("_(no evidence yet)_");+ }+ lines.push("");+ lines.push("## How to apply", "");+ const guidance = input.howToApply?.trim();+ if (guidance) {+ lines.push(guidance.replace(/\r\n?/g, "\n").replace(/\s+$/g, ""));+ } else {+ lines.push("_(not provided)_");+ }+ return lines.join("\n");+}++// ----- Parsers --------------------------------------------------------------++/**+ * Parse a preference file. Defaults `pinned` to `false` when the field+ * is absent (Β§5.3). Throws {@link BrainStatusFolderMismatchError} when+ * the file lives in `preferences/` but its `status` reads `retired`+ * (or any other state outside `unconfirmed` / `confirmed`).+ */+export function parsePreference(path: string): BrainPreference {+ const [meta, _body] = parseFrontmatter(path);+ // `_body` is unused for preferences β the body is purely human prose;+ // every machine-actionable field lives in the frontmatter.+ void _body;++ requireField(meta, "kind", path);+ if (meta["kind"] !== "brain-preference") {+ throw new Error(+ `preference kind must be 'brain-preference'; got ${JSON.stringify(meta["kind"])} (${path})`,+ );+ }++ const status = requireString(meta, "status", path);+ // Reject unknown status values BEFORE the folder invariant: a malformed+ // file should never coerce into a typed `BrainPreference.status`+ // downstream, regardless of which folder it sits in. We tolerate+ // `status: "retired"` here because that case is the dedicated+ // status-folder-mismatch the parser surfaces below as a typed error+ // (doctor downgrades it to a warning) β see Β§4 of the design doc.+ const statusValues = Object.values(BRAIN_PREFERENCE_STATUS) as ReadonlyArray<string>;+ if (!statusValues.includes(status) && status !== "retired") {+ throw new Error(+ `preference status must be one of ${statusValues.join(", ")}; got ${JSON.stringify(status)} (${path})`,+ );+ }+ enforceStatusFolderInvariant(path, status, "preferences");++ const id = requireString(meta, "id", path);+ const created_at = requireString(meta, "created_at", path);+ const unconfirmed_until = requireString(meta, "unconfirmed_until", path);+ const tags = requireStringArray(meta, "tags", path);+ const topic = requireString(meta, "topic", path);+ const principle = requireString(meta, "principle", path);++ const evidenced_by = optionalStringArray(meta, "evidenced_by");+ const confirmed_at = optionalNullableString(meta, "confirmed_at");+ const last_evidence_at = optionalNullableString(meta, "last_evidence_at");++ const result: BrainPreference = {+ kind: "brain-preference",+ id,+ created_at,+ confirmed_at,+ unconfirmed_until,+ tags,+ topic,+ status: status as BrainPreferenceStatus,+ principle,+ evidenced_by,+ applied_count: optionalNumber(meta, "applied_count", 0),+ violated_count: optionalNumber(meta, "violated_count", 0),+ last_evidence_at,+ confidence: parseConfidence(meta, path),+ pinned: parsePinned(meta),+ ...(optionalScalarString(meta, "scope") !== undefined+ ? { scope: optionalScalarString(meta, "scope") }+ : {}),+ ...(optionalScalarString(meta, "supersedes") !== undefined+ ? { supersedes: optionalScalarString(meta, "supersedes") }+ : {}),+ ...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])+ ? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }+ : {}),+ };+ return Object.freeze(result);+}++/**+ * Parse a retired-preference file. Mirrors {@link parsePreference} but+ * enforces the `retired/` folder invariant and validates the+ * `retired_reason` enum.+ */+export function parseRetired(path: string): BrainRetired {+ const [meta] = parseFrontmatter(path);++ requireField(meta, "kind", path);+ if (meta["kind"] !== "brain-retired") {+ throw new Error(+ `retired kind must be 'brain-retired'; got ${JSON.stringify(meta["kind"])} (${path})`,+ );+ }++ const status = requireString(meta, "status", path);+ if (status !== "retired") {+ throw new BrainStatusFolderMismatchError(+ "retired file frontmatter status is not 'retired'",+ path,+ status,+ "retired",+ );+ }+ enforceStatusFolderInvariant(path, status, "retired");++ const id = requireString(meta, "id", path);+ const retired_at = requireString(meta, "retired_at", path);+ const reasonStr = requireString(meta, "retired_reason", path);+ const reasonValues = Object.values(BRAIN_RETIRED_REASON) as ReadonlyArray<string>;+ if (!reasonValues.includes(reasonStr)) {+ throw new Error(+ `retired_reason must be one of ${reasonValues.join(", ")}; got ${JSON.stringify(reasonStr)} (${path})`,+ );+ }+ const retired_by = requireString(meta, "retired_by", path);+ const created_at = requireString(meta, "created_at", path);+ const tags = requireStringArray(meta, "tags", path);+ const topic = requireString(meta, "topic", path);+ const principle = requireString(meta, "principle", path);++ const result: BrainRetired = {+ kind: "brain-retired",+ id,+ status: "retired",+ retired_at,+ retired_reason: reasonStr as BrainRetiredReason,+ retired_by,+ created_at,+ tags,+ topic,+ principle,+ evidenced_by: optionalStringArray(meta, "evidenced_by"),+ applied_count: optionalNumber(meta, "applied_count", 0),+ violated_count: optionalNumber(meta, "violated_count", 0),+ last_evidence_at: optionalNullableString(meta, "last_evidence_at"),+ confidence: parseConfidence(meta, path),+ pinned: parsePinned(meta),+ ...(optionalScalarString(meta, "scope") !== undefined+ ? { scope: optionalScalarString(meta, "scope") }+ : {}),+ ...(optionalScalarString(meta, "superseded_by") !== undefined+ ? { superseded_by: optionalScalarString(meta, "superseded_by") }+ : {}),+ ...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])+ ? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }+ : {}),+ };+ return Object.freeze(result);+}++// ----- preferences/ -> retired/ mover --------------------------------------++/**+ * Move a preference into `Brain/retired/`. Rewrites the frontmatter+ * with the retire metadata (status, kind, retired_at, retired_reason,+ * retired_by, optional superseded_by) and preserves the inherited+ * fields (topic, principle, evidenced_by, β¦).+ *+ * Body decision: we keep the original "## Principle" / "## Origin" /+ * "## How to apply" sections and append a "## Retired" section that+ * names the reason and pointer. The design doc Β§5.4 is silent on the+ * body shape; keeping the prose intact (rather than truncating it)+ * preserves the audit trail value β a future reader sees both what the+ * rule was and why it left.+ *+ * The move is performed as: write the new file atomically under+ * `retired/`, then `unlink` the original under `preferences/`. If the+ * write fails, the original stays untouched. If the unlink fails after+ * a successful write, the caller is left with both copies β `o2b brain+ * doctor` flags the duplicate id.+ */+export function moveToRetired(+ vault: string,+ prefPath: string,+ reason: BrainRetiredReason,+ opts: MoveToRetiredOptions,+): MoveToRetiredResult {+ // Pre-condition: ensure the source path is actually inside the+ // canonical `preferences/` folder. Doing this check *before* any I/O+ // means a buggy caller cannot trick us into deleting an unrelated+ // file: a misrouted call fails fast with no destructive side effect.+ const dirs = brainDirs(vault);+ if (dirname(prefPath) !== dirs.preferences) {+ throw new Error(+ `moveToRetired: source path was not under preferences/: ${prefPath}`,+ );+ }++ const [meta, body] = parseFrontmatter(prefPath);+ if (meta["kind"] !== "brain-preference") {+ throw new Error(+ `moveToRetired: expected a preference file; got kind ${JSON.stringify(meta["kind"])} (${prefPath})`,+ );+ }+ const oldId = requireString(meta, "id", prefPath);+ if (!oldId.startsWith("pref-")) {+ throw new Error(+ `moveToRetired: preference id must start with 'pref-'; got ${oldId} (${prefPath})`,+ );+ }+ const slug = oldId.slice("pref-".length);+ if (!slug) {+ throw new Error(`moveToRetired: empty slug derived from id ${oldId}`);+ }++ const newId = `ret-${slug}`;+ const newPath = retiredPath(vault, slug);++ // Build the new frontmatter map. We preserve every inherited field+ // verbatim (`topic`, `principle`, `evidenced_by`, counters, β¦), drop+ // the active-state fields that no longer apply (`unconfirmed_until`,+ // `confirmed_at`), and stamp the retire metadata on top.+ const newMeta: FrontmatterMap = {};+ for (const [k, v] of Object.entries(meta)) {+ if (k === "kind" || k === "id" || k === "status") continue;+ if (k === "unconfirmed_until" || k === "confirmed_at") continue;+ if (k === "tags") {+ // Replace the `brain/preference` tag with `brain/retired`.+ const arr = Array.isArray(v) ? [...v] : [];+ newMeta["tags"] = arr.map((t) =>+ t === "brain/preference" ? "brain/retired" : t,+ );+ continue;+ }+ newMeta[k] = v as never;+ }+ newMeta["kind"] = "brain-retired";+ newMeta["id"] = newId;+ newMeta["status"] = "retired";+ newMeta["retired_at"] = opts.now.toISOString();+ newMeta["retired_reason"] = reason;+ newMeta["retired_by"] = opts.retired_by;+ if (opts.superseded_by?.trim()) {+ newMeta["superseded_by"] = opts.superseded_by.trim();+ }++ // Add the prior `pref-<slug>` basename as an Obsidian alias on the+ // retired file. Wikilinks in append-only logs and signal frontmatter+ // were written when the file still lived in `preferences/`; without+ // this alias they would stop resolving the moment the file is+ // renamed. Obsidian's wikilink resolver checks `aliases` after+ // basename, so `[[pref-<slug>]]` continues to land on the right note+ // without rewriting any historical entry.+ const existingAliases = Array.isArray(newMeta["aliases"])+ ? (newMeta["aliases"] as ReadonlyArray<string>)+ : [];+ if (!existingAliases.includes(oldId)) {+ newMeta["aliases"] = [oldId, ...existingAliases];+ }++ const newBody = appendRetiredSection(body, reason, opts);++ writeFrontmatterAtomic(newPath, newMeta, newBody, {+ overwrite: false,+ existsErrorKind: "retired",+ vaultForRelativePath: vault,+ });++ // Confirm the new file actually landed before unlinking the source.+ if (!existsSync(newPath)) {+ throw new Error(+ `moveToRetired: write of ${newPath} reported success but file is absent`,+ );+ }+ unlinkSync(prefPath);++ return { path: newPath, id: newId };+}++function appendRetiredSection(+ body: string,+ reason: BrainRetiredReason,+ opts: MoveToRetiredOptions,+): string {+ const trimmed = body.trimEnd();+ const block: string[] = [+ "",+ "",+ "## Retired",+ "",+ `Reason: \`${reason}\``,+ `Retired at: ${opts.now.toISOString()}`,+ `Retired by: ${opts.retired_by}`,+ ];+ if (opts.superseded_by?.trim()) {+ block.push(`Superseded by: ${opts.superseded_by.trim()}`);+ }+ return trimmed + block.join("\n") + "\n";+}++// ----- Field helpers --------------------------------------------------------++function enforceStatusFolderInvariant(+ path: string,+ status: string,+ expectedFolder: "preferences" | "retired",+): void {+ // Resolve the immediate parent directory's basename. Files outside+ // the canonical `Brain/<folder>/...` get a softer treatment: we let+ // the caller use the parser on a synthetic path (e.g. tests writing+ // to a tmpdir) so long as the status itself is coherent.+ const parent = basename(dirname(path));+ if (expectedFolder === "preferences") {+ // We accept `preferences` as the canonical folder. A status of+ // `retired` here is the mismatch case the design doc Β§4 calls out.+ if (parent === "preferences" && status !== BRAIN_PREFERENCE_STATUS.unconfirmed && status !== BRAIN_PREFERENCE_STATUS.confirmed) {+ throw new BrainStatusFolderMismatchError(+ "preference file frontmatter status does not match preferences/ folder",+ path,+ status,+ "preferences",+ );+ }+ } else {+ if (parent === "retired" && status !== "retired") {+ throw new BrainStatusFolderMismatchError(+ "retired file frontmatter status does not match retired/ folder",+ path,+ status,+ "retired",+ );+ }+ }+}++function requireField(+ meta: Record<string, unknown>,+ field: string,+ path: string,+): void {+ if (!(field in meta) || meta[field] === undefined || meta[field] === null) {+ throw new Error(`preference missing field: ${field} (${path})`);+ }+ if (typeof meta[field] === "string" && (meta[field] as string).trim() === "") {+ throw new Error(`preference missing field: ${field} (${path})`);+ }+}++function requireString(+ meta: Record<string, unknown>,+ field: string,+ path: string,+): string {+ requireField(meta, field, path);+ const v = meta[field];+ if (typeof v !== "string") {+ throw new Error(`preference field '${field}' must be a string (${path})`);+ }+ return v;+}++function requireStringArray(+ meta: Record<string, unknown>,+ field: string,+ path: string,+): ReadonlyArray<string> {+ requireField(meta, field, path);+ const v = meta[field];+ if (!Array.isArray(v)) {+ throw new Error(`preference field '${field}' must be an array (${path})`);+ }+ for (const item of v) {+ if (typeof item !== "string") {+ throw new Error(+ `preference field '${field}' must be an array of strings (${path})`,+ );+ }+ }+ return [...(v as ReadonlyArray<string>)];+}++function optionalStringArray(+ meta: Record<string, unknown>,+ field: string,+): ReadonlyArray<string> {+ const v = meta[field];+ if (v === undefined || v === null) return [];+ if (!Array.isArray(v)) {+ throw new Error(`preference field '${field}' must be an array`);+ }+ for (const item of v) {+ if (typeof item !== "string") {+ throw new Error(+ `preference field '${field}' must be an array of strings`,+ );+ }+ }+ return [...(v as ReadonlyArray<string>)];+}++/**+ * Parse a string field whose semantic value is nullable. Both the+ * literal string `"null"` and an empty string surface as JS `null` so+ * the on-disk roundtrip survives the simple YAML emitter (which has no+ * native null token).+ */+function optionalNullableString(+ meta: Record<string, unknown>,+ field: string,+): string | null {+ const v = meta[field];+ if (v === undefined || v === null) return null;+ if (typeof v !== "string") {+ throw new Error(`preference field '${field}' must be a string or null`);+ }+ const trimmed = v.trim();+ if (trimmed === "" || trimmed === "null") return null;+ return v;+}++function optionalNumber(+ meta: Record<string, unknown>,+ field: string,+ fallback: number,+): number {+ const v = meta[field];+ if (v === undefined || v === null || v === "") return fallback;+ // The simple parser surfaces all values as strings; numerics included.+ if (typeof v === "number") return v;+ if (typeof v === "string") {+ const n = Number(v);+ if (!Number.isFinite(n)) {+ throw new Error(+ `preference field '${field}' must be a finite number; got ${JSON.stringify(v)}`,+ );+ }+ return n;+ }+ throw new Error(`preference field '${field}' must be a number`);+}++function optionalScalarString(+ meta: Record<string, unknown>,+ field: string,+): string | undefined {+ const v = meta[field];+ if (v === undefined || v === null) return undefined;+ if (typeof v !== "string") return undefined;+ const trimmed = v.trim();+ return trimmed === "" ? undefined : v;+}++function parseConfidence(+ meta: Record<string, unknown>,+ path: string,+): BrainConfidence {+ const v = meta["confidence"];+ if (v === undefined || v === null || v === "") return BRAIN_CONFIDENCE.low;+ if (typeof v !== "string") {+ throw new Error(`preference field 'confidence' must be a string (${path})`);+ }+ const values = Object.values(BRAIN_CONFIDENCE) as ReadonlyArray<string>;+ if (!values.includes(v)) {+ throw new Error(+ `preference field 'confidence' must be one of ${values.join(", ")}; got ${JSON.stringify(v)} (${path})`,+ );+ }+ return v as BrainConfidence;+}++/**+ * Coerce `pinned` to boolean with a hard default of `false`. Accepts+ * the literal string forms ("true"/"false") emitted by the simple+ * formatter and the native boolean if a richer parser ever lands.+ */+function parsePinned(meta: Record<string, unknown>): boolean {+ const v = meta["pinned"];+ if (v === undefined || v === null || v === "") return false;+ if (typeof v === "boolean") return v;+ if (typeof v === "string") {+ if (v === "true") return true;+ if (v === "false") return false;+ }+ // Unexpected representations fall back to false; we treat this as a+ // forward-compat soft default rather than an error so a hand-edited+ // file with an oddly-quoted boolean still parses.+ return false;+}++// Internal use only: prevent "unused variable" lint after destructuring.+void join;diff --git a/src/core/brain/query.ts b/src/core/brain/query.tsnew file mode 100644index 00000000..e883ae6b--- /dev/null+++ b/src/core/brain/query.ts@@ -0,0 +1,373 @@+/**+ * Read-only query helpers over Brain state (design doc Β§9.2).+ *+ * Three callable shapes, all returning frozen result objects so the+ * surfaces consuming them (CLI `o2b brain query`, MCP `brain_query`,+ * future agent introspection) cannot accidentally mutate vault state:+ *+ * - {@link queryByPreference} β one preference (active or retired)+ * plus every `apply-evidence` log entry that references it.+ *+ * - {@link queryByTopic} β every signal under a topic (active ++ * processed), the current preference for that topic (active or+ * retired), and every log entry mentioning the preference.+ *+ * - {@link queryByLogSince} β every log entry across all days whose+ * `timestamp >= since`. Cron / digest / debugging entry point.+ *+ * All three are pure reads. They do not touch the inbox `processed/`+ * holding area, the snapshots/, or the `_brain.yaml` config β those are+ * dream's job.+ *+ * Wikilink resolution rule: a preference is "referenced" by a log entry+ * when the entry's `preference` payload contains either the bare id or+ * the `[[id]]` wikilink form. We strip both forms so a hand-typed entry+ * (`preference: pref-foo`) and a properly-rendered entry+ * (`preference: [[pref-foo]]`) both match.+ */++import { existsSync, readdirSync } from "node:fs";+import { join } from "node:path";++import { brainDirs } from "./paths.ts";+import { parseLogDay, type BrainLogEntry } from "./log.ts";+import { parsePreference, parseRetired } from "./preference.ts";+import { parseSignal } from "./signal.ts";+import { normaliseWikilinkTarget } from "./wikilink.ts";+import { BRAIN_LOG_EVENT_KIND } from "./types.ts";+import type {+ BrainPreference,+ BrainRetired,+ BrainSignal,+} from "./types.ts";++// ----- Errors ---------------------------------------------------------------++/**+ * Raised when {@link queryByPreference} is asked for a `pref-` id (or+ * `ret-` id) that resolves to no file in either `preferences/` or+ * `retired/`. The CLI translates this to exit code `2` per design doc+ * Β§9.2 "not an error condition".+ */+export class BrainNotFoundError extends Error {+ readonly id: string;++ constructor(id: string) {+ super(`brain query: no preference or retired entry found for id '${id}'`);+ this.name = "BrainNotFoundError";+ this.id = id;+ }+}++// ----- Result shapes --------------------------------------------------------++export interface QueryByPreferenceResult {+ /** The active preference (`preferences/`) or retired one (`retired/`). */+ readonly preference: BrainPreference | BrainRetired;+ /**+ * Every `apply-evidence` log entry referencing this preference,+ * sorted ascending by `timestamp`. Empty when the preference exists+ * but has never been applied (common for freshly-promoted+ * unconfirmed entries).+ */+ readonly evidence: ReadonlyArray<BrainLogEntry>;+}++export interface QueryByTopicResult {+ /**+ * All signals for the topic β active (`inbox/sig-*.md`) and processed+ * (`inbox/processed/sig-*.md`). Sorted by `created_at` ascending so+ * the caller sees a chronological trail.+ */+ readonly signals: ReadonlyArray<BrainSignal>;+ /**+ * The current state of the topic's rule:+ * - active preference if one exists in `preferences/`+ * - retired preference if one exists in `retired/`+ * - null if the topic has signals but never reached promotion+ *+ * A topic can plausibly have *both* an active and a retired entry+ * (the active rule supersedes a prior retired one). In that case we+ * return the active version β it is the current truth β and the+ * caller can find the historical retired one via `queryByPreference`+ * by id.+ */+ readonly preference: BrainPreference | BrainRetired | null;+ /**+ * Every log entry mentioning the topic's preference id. Sorted by+ * `timestamp` ascending. Includes `apply-evidence`, `promote`,+ * `retire`, `pin` / `unpin`, etc. β anything whose `preference`+ * payload field resolves to the same id.+ */+ readonly all_log_events: ReadonlyArray<BrainLogEntry>;+}++// ----- Public API -----------------------------------------------------------++/**+ * Look up one preference (active or retired) and its evidence trail.+ *+ * Resolution rules:+ * - A `pref-...` id is searched in `preferences/`. If absent, we also+ * accept a fallback to `retired/ret-<slug>` (same slug stem) so an+ * agent that asked for the active id of a now-retired preference+ * still gets a useful answer.+ * - A `ret-...` id is searched in `retired/` only.+ * - Any other prefix raises {@link BrainNotFoundError} immediately.+ */+export function queryByPreference(+ vault: string,+ pref_id: string,+): QueryByPreferenceResult {+ const id = pref_id.trim();+ if (!id) {+ throw new BrainNotFoundError(pref_id);+ }+ // Slug shape is the same alphabet validateSlug() enforces; rejecting+ // here before forming any filesystem path closes a path-traversal+ // vector (`pref-../../etc/passwd`) β even though `validateSlug` would+ // catch it later, we never want `join(dirs.preferences, ...)` to+ // resolve outside the intended directory under any operator error.+ const SLUG_RE = /^[A-Za-z0-9._-]+$/;+ const dirs = brainDirs(vault);+ let preference: BrainPreference | BrainRetired | null = null;++ if (id.startsWith("pref-")) {+ const slug = id.slice("pref-".length);+ if (!SLUG_RE.test(slug)) {+ throw new BrainNotFoundError(pref_id);+ }+ const activePath = join(dirs.preferences, `${id}.md`);+ if (existsSync(activePath)) {+ preference = parsePreference(activePath);+ } else {+ // Fallback to the retired version with the same slug stem.+ const retiredPathCandidate = join(dirs.retired, `ret-${slug}.md`);+ if (existsSync(retiredPathCandidate)) {+ preference = parseRetired(retiredPathCandidate);+ }+ }+ } else if (id.startsWith("ret-")) {+ const slug = id.slice("ret-".length);+ if (!SLUG_RE.test(slug)) {+ throw new BrainNotFoundError(pref_id);+ }+ const retiredPathCandidate = join(dirs.retired, `${id}.md`);+ if (existsSync(retiredPathCandidate)) {+ preference = parseRetired(retiredPathCandidate);+ }+ } else {+ throw new BrainNotFoundError(pref_id);+ }++ if (!preference) {+ throw new BrainNotFoundError(pref_id);+ }++ // The evidence trail is keyed off the active id (`pref-<slug>`) β the+ // log records `preference: [[pref-<slug>]]` even after retirement.+ const slug = preference.id.startsWith("pref-")+ ? preference.id.slice("pref-".length)+ : preference.id.slice("ret-".length);+ const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);++ const all = readAllLogEntries(vault);+ const evidence = all+ .filter(+ (e) =>+ e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence &&+ matchPreferencePayload(e.body["preference"], matchIds),+ )+ .sort(byTimestampAsc);++ return Object.freeze({+ preference,+ evidence: Object.freeze(evidence),+ });+}++/**+ * Aggregate every artifact under a topic. Includes signals across both+ * `inbox/` and `inbox/processed/`, the current rule (active or+ * retired), and every log entry mentioning the preference id (active+ * or retired form). Unknown topic β empty result with `preference: null`.+ */+export function queryByTopic(+ vault: string,+ topic: string,+): QueryByTopicResult {+ const want = topic.trim();+ if (!want) {+ return Object.freeze({+ signals: Object.freeze([]),+ preference: null,+ all_log_events: Object.freeze([]),+ });+ }++ const dirs = brainDirs(vault);+ const signals: BrainSignal[] = [];++ // Collect signals from both inbox/ and inbox/processed/. We do not+ // recurse β `inbox/processed/` is the only allowed sub-folder of+ // `inbox/` and `readdirSync` with `withFileTypes` lets us pick file+ // vs directory entries deterministically.+ collectSignals(dirs.inbox, want, signals);+ collectSignals(dirs.processed, want, signals);+ signals.sort((a, b) => a.created_at.localeCompare(b.created_at));++ // Current rule β prefer the active preference; fall back to retired.+ let preference: BrainPreference | BrainRetired | null = null;+ preference = findPreferenceForTopic(dirs.preferences, want, "preference");+ if (!preference) {+ preference = findPreferenceForTopic(dirs.retired, want, "retired");+ }++ // All log events whose `preference` payload resolves to the topic's+ // pref id (both `pref-` and `ret-` forms, since the slug stem is+ // shared after retirement).+ let all_log_events: ReadonlyArray<BrainLogEntry> = Object.freeze([]);+ if (preference) {+ const slug = preference.id.startsWith("pref-")+ ? preference.id.slice("pref-".length)+ : preference.id.slice("ret-".length);+ const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);+ const all = readAllLogEntries(vault);+ all_log_events = Object.freeze(+ all+ .filter((e) => matchPreferencePayload(e.body["preference"], matchIds))+ .sort(byTimestampAsc),+ );+ }++ return Object.freeze({+ signals: Object.freeze(signals),+ preference,+ all_log_events,+ });+}++/**+ * Return every log entry across `Brain/log/*.md` whose `timestamp` is+ * `>= since` (inclusive lower bound β same semantics as the digest's+ * window). Entries are returned in chronological order. Malformed log+ * entries are silently skipped (their warnings are the doctor's+ * concern, not this surface's).+ */+export function queryByLogSince(+ vault: string,+ since: Date,+): ReadonlyArray<BrainLogEntry> {+ if (!(since instanceof Date) || Number.isNaN(since.getTime())) {+ throw new TypeError("queryByLogSince: `since` must be a valid Date");+ }+ const sinceIso = since.toISOString();+ const entries = readAllLogEntries(vault).filter(+ (e) => e.timestamp >= sinceIso,+ );+ entries.sort(byTimestampAsc);+ return Object.freeze(entries);+}++// ----- Internals ------------------------------------------------------------++/**+ * Read every log file under `Brain/log/`, parse it via {@link parseLogDay},+ * and concatenate the entries in chronological order (each file is+ * already in-order; we glue them by date prefix). Missing log directory+ * β empty array.+ */+export function readAllLogEntries(vault: string): BrainLogEntry[] {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.log)) return [];+ const names = readdirSync(dirs.log, { withFileTypes: true })+ .filter((d) => d.isFile() && d.name.endsWith(".md"))+ .map((d) => d.name.slice(0, -".md".length))+ .filter((n) => /^\d{4}-\d{2}-\d{2}$/.test(n))+ .sort();+ const out: BrainLogEntry[] = [];+ for (const date of names) {+ const { entries } = parseLogDay(vault, date);+ for (const e of entries) out.push(e);+ }+ return out;+}++function collectSignals(+ dir: string,+ topic: string,+ out: BrainSignal[],+): void {+ if (!existsSync(dir)) return;+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ if (!entry.isFile()) continue;+ if (!entry.name.startsWith("sig-") || !entry.name.endsWith(".md")) {+ continue;+ }+ let sig: BrainSignal;+ try {+ sig = parseSignal(join(dir, entry.name));+ } catch {+ // Corrupted frontmatter is the doctor's concern; queries skip.+ continue;+ }+ if (sig.topic === topic) out.push(sig);+ }+}++function findPreferenceForTopic(+ dir: string,+ topic: string,+ kind: "preference" | "retired",+): BrainPreference | BrainRetired | null {+ if (!existsSync(dir)) return null;+ const prefix = kind === "preference" ? "pref-" : "ret-";+ // Sort by filename so the "first match" is deterministic across runs+ // and filesystems. `readdirSync` order is platform-dependent (it is+ // explicitly unspecified by POSIX and by Node) β without an explicit+ // sort, two preferences with the same topic could be returned in+ // different orders on different machines.+ const entries = readdirSync(dir, { withFileTypes: true })+ .slice()+ .sort((a, b) => a.name.localeCompare(b.name));+ for (const entry of entries) {+ if (!entry.isFile()) continue;+ if (!entry.name.startsWith(prefix) || !entry.name.endsWith(".md")) {+ continue;+ }+ const path = join(dir, entry.name);+ try {+ const parsed =+ kind === "preference" ? parsePreference(path) : parseRetired(path);+ if (parsed.topic === topic) return parsed;+ } catch {+ // Doctor's job, not query's.+ continue;+ }+ }+ return null;+}++/**+ * The `preference` payload field of an `apply-evidence` (or `promote`,+ * `retire`, β¦) log entry is typically a wikilink (`[[pref-foo]]`) but+ * we tolerate the bare id form and even a sub-path/alias suffix. Strip+ * brackets, drop everything after `|` or `#`, then compare against the+ * caller's set of allowed ids.+ */+function matchPreferencePayload(+ payload: string | ReadonlyArray<string> | undefined,+ matchIds: ReadonlySet<string>,+): boolean {+ if (payload === undefined) return false;+ const values = Array.isArray(payload) ? payload : [payload as string];+ for (const v of values) {+ const id = normaliseWikilinkTarget(v);+ if (id && matchIds.has(id)) return true;+ }+ return false;+}++function byTimestampAsc(a: BrainLogEntry, b: BrainLogEntry): number {+ return a.timestamp.localeCompare(b.timestamp);+}diff --git a/src/core/brain/signal.ts b/src/core/brain/signal.tsnew file mode 100644index 00000000..308b8d7d--- /dev/null+++ b/src/core/brain/signal.ts@@ -0,0 +1,337 @@+/**+ * Signal (`sig-*.md`) parser and writer.+ *+ * Signals are the immutable raw input to the dream algorithm. Each one+ * is a single Markdown file under `Brain/inbox/` (or `processed/` once+ * folded into a preference). The frontmatter shape is fully specified+ * in design doc Β§5.2 and mirrored on the `BrainSignal` interface in+ * `./types.ts`.+ *+ * This module exposes a parser + writer pair:+ *+ * - `parseSignal(path)` validates required fields, returns a frozen+ * `BrainSignal` (mutation throws). Missing required fields surface+ * as `Error('signal missing field: <name>')` so the caller knows+ * exactly which field is wrong.+ *+ * - `writeSignal(vault, input, options)` allocates a free slug under+ * `Brain/inbox/`, writes the file atomically through `fs-atomic`,+ * and returns the resulting path + id. Slug collisions are resolved+ * by `allocateSlug` (suffixes `-2`, `-3`, β¦).+ *+ * The body shape ("## Raw" section with the optional `raw` text) is+ * deterministic so two writes with identical input produce byte-for-byte+ * identical files β a property exercised by the roundtrip test.+ */++import type { FrontmatterMap } from "../types.ts";+import { writeFrontmatterAtomic, parseFrontmatter } from "../vault.ts";+import { allocateSlug, brainDirs, validateIsoDate } from "./paths.ts";+import {+ BRAIN_SIGNAL_SIGN,+ type BrainSignal,+ type BrainSignalSign,+} from "./types.ts";++/** Filename prefix without the trailing dash, e.g. `sig-2026-05-14`. */+function signalPrefix(date: string): string {+ return `sig-${validateIsoDate(date)}`;+}++/**+ * Input contract for {@link writeSignal}. Mirrors the design-doc Β§5.2+ * required/optional split. `slug` is the slug stem only (no `sig-` or+ * date prefix); the writer composes the final filename.+ *+ * `created_at` is included so callers can write deterministic+ * fixtures; production callers pass `new Date().toISOString()`.+ */+export interface WriteSignalInput {+ readonly topic: string;+ readonly signal: BrainSignalSign;+ readonly agent: string;+ readonly principle: string;+ readonly created_at: string;+ /** Calendar date (UTC) used in the filename and the `created_at`. */+ readonly date: string;+ /** Slug stem; collision is resolved by `allocateSlug` suffixes. */+ readonly slug: string;+ readonly scope?: string;+ readonly source?: ReadonlyArray<string>;+ /** Free-form body that follows the frontmatter under "## Raw". */+ readonly raw?: string;+ /** Optional extra tags merged after the canonical set. */+ readonly extraTags?: ReadonlyArray<string>;+}++export interface WriteSignalOptions {+ /** Maximum collision suffixes to try; defaults to allocateSlug's cap. */+ readonly maxSlugAttempts?: number;+}++export interface WriteSignalResult {+ readonly path: string;+ readonly id: string;+}++const REQUIRED_INPUT_FIELDS: ReadonlyArray<keyof WriteSignalInput> = [+ "topic",+ "signal",+ "agent",+ "principle",+ "created_at",+ "date",+ "slug",+];++/**+ * Write a signal atomically. Funnels through {@link allocateSlug} so a+ * second call with the same slug receives a `-2` suffix automatically.+ *+ * The body is the canonical "## Raw" section. When `raw` is omitted, the+ * section is rendered with an `_(not provided)_` placeholder so every+ * signal has the same heading structure β consistent with the Pay+ * Memory receipt style.+ */+export function writeSignal(+ vault: string,+ input: WriteSignalInput,+ options: WriteSignalOptions = {},+): WriteSignalResult {+ for (const field of REQUIRED_INPUT_FIELDS) {+ const value = input[field];+ if (value === undefined || value === null || String(value).trim() === "") {+ throw new Error(`signal missing field: ${String(field)}`);+ }+ }+ if (+ input.signal !== BRAIN_SIGNAL_SIGN.positive &&+ input.signal !== BRAIN_SIGNAL_SIGN.negative+ ) {+ throw new Error(+ `signal field 'signal' must be 'positive' or 'negative'; got ${JSON.stringify(input.signal)}`,+ );+ }++ const dirs = brainDirs(vault);+ const allocated = allocateSlug({+ vault,+ targetDir: dirs.inbox,+ prefix: signalPrefix(input.date),+ slug: input.slug,+ maxAttempts: options.maxSlugAttempts,+ });++ // The on-disk id always equals the filename basename, including any+ // `-2`/`-3` collision suffix. We surface that as the canonical id and+ // duplicate it inside the frontmatter so manual `mv` keeps the link.+ const id = `${signalPrefix(input.date)}-${allocated.slug}`;++ const tags = composeSignalTags(input);+ const metadata: FrontmatterMap = {+ kind: "brain-signal",+ id,+ created_at: input.created_at,+ tags: [...tags],+ topic: input.topic.trim(),+ signal: input.signal,+ agent: input.agent.trim(),+ principle: input.principle.trim(),+ };+ // Optional fields: keep the file lean. The parser tolerates absence and+ // returns `undefined` on the interface β no `_(not provided)_` for+ // metadata.+ if (input.scope && input.scope.trim()) {+ metadata["scope"] = input.scope.trim();+ }+ if (input.source && input.source.length > 0) {+ metadata["source"] = [...input.source];+ }++ const body = renderSignalBody(input);+ writeFrontmatterAtomic(allocated.path, metadata, body, {+ overwrite: false,+ existsErrorKind: "signal",+ vaultForRelativePath: vault,+ });++ return { path: allocated.path, id };+}++/**+ * Read a signal file from disk and validate its frontmatter against the+ * `BrainSignal` contract. Returns a frozen object β the parsed shape is+ * immutable at runtime to match the `readonly` declarations on the type.+ *+ * Throws `Error('signal missing field: <name>')` for any absent required+ * field. `signal` value mismatch (anything outside positive/negative)+ * surfaces as a separate, distinguishable error.+ */+export function parseSignal(path: string): BrainSignal {+ const [meta, body] = parseFrontmatter(path);++ requireField(meta, "kind");+ if (meta["kind"] !== "brain-signal") {+ throw new Error(+ `signal kind must be 'brain-signal'; got ${JSON.stringify(meta["kind"])} (${path})`,+ );+ }+ const id = requireString(meta, "id");+ const created_at = requireString(meta, "created_at");+ const tags = requireStringArray(meta, "tags");+ const topic = requireString(meta, "topic");+ const signalValue = requireString(meta, "signal");+ if (+ signalValue !== BRAIN_SIGNAL_SIGN.positive &&+ signalValue !== BRAIN_SIGNAL_SIGN.negative+ ) {+ throw new Error(+ `signal field 'signal' must be 'positive' or 'negative'; got ${JSON.stringify(signalValue)} (${path})`,+ );+ }+ const agent = requireString(meta, "agent");+ const principle = requireString(meta, "principle");++ // Optional fields. `scope` is a plain scalar; `source` is an inline+ // array of wikilink strings. `raw` is extracted from the body if the+ // canonical heading is present.+ let scope: string | undefined;+ if (meta["scope"] !== undefined) {+ const s = meta["scope"];+ if (typeof s !== "string") {+ throw new Error(`signal field 'scope' must be a string (${path})`);+ }+ if (s.trim()) scope = s.trim();+ }++ let source: ReadonlyArray<string> | undefined;+ if (meta["source"] !== undefined) {+ if (!Array.isArray(meta["source"])) {+ throw new Error(`signal field 'source' must be an array (${path})`);+ }+ for (const item of meta["source"]) {+ if (typeof item !== "string") {+ throw new Error(+ `signal field 'source' must be an array of strings (${path})`,+ );+ }+ }+ source = [...(meta["source"] as ReadonlyArray<string>)];+ }++ const raw = extractRawSection(body);++ const result: BrainSignal = {+ kind: "brain-signal",+ id,+ created_at,+ tags,+ topic,+ signal: signalValue as BrainSignalSign,+ agent,+ principle,+ ...(scope !== undefined ? { scope } : {}),+ ...(source !== undefined ? { source } : {}),+ ...(raw !== undefined ? { raw } : {}),+ };+ return Object.freeze(result);+}++// ----- Helpers --------------------------------------------------------------++/**+ * Build the canonical tag set: `brain`, `brain/signal`, plus per-topic+ * and (optionally) per-scope tags. Any `extraTags` supplied by the+ * caller are appended after dedup. We preserve insertion order so the+ * file is byte-stable across writes with identical input.+ */+function composeSignalTags(input: WriteSignalInput): string[] {+ const out: string[] = [];+ const seen = new Set<string>();+ const push = (t: string): void => {+ if (!seen.has(t)) {+ seen.add(t);+ out.push(t);+ }+ };+ push("brain");+ push("brain/signal");+ push(`brain/topic/${input.topic.trim()}`);+ if (input.scope && input.scope.trim()) {+ push(`brain/scope/${input.scope.trim()}`);+ }+ for (const t of input.extraTags ?? []) {+ if (t.trim()) push(t.trim());+ }+ return out;+}++/**+ * Render the body. The "## Raw" section is always present so the file+ * shape is identical regardless of whether `raw` was provided β+ * deterministic write is part of the contract.+ */+function renderSignalBody(input: WriteSignalInput): string {+ const lines: string[] = ["## Raw", ""];+ if (input.raw && input.raw.trim()) {+ // Normalise line endings and trailing whitespace so two callers+ // passing semantically-equal text produce byte-identical output.+ lines.push(input.raw.replace(/\r\n?/g, "\n").replace(/\s+$/g, ""));+ } else {+ lines.push("_(not provided)_");+ }+ return lines.join("\n");+}++function extractRawSection(body: string): string | undefined {+ // The signal body is exactly one "## Raw" section. Capture everything+ // after it until EOF (no further headings in this schema). Returning+ // `undefined` for the placeholder keeps the type shape clean.+ //+ // No `m` flag: with multiline mode `$` matches end-of-line, which+ // truncates the lazy `[\s\S]*?` capture at the first newline instead+ // of running to EOF. We anchor the heading at start-of-string with an+ // explicit `(?:^|\n)` and let `$` mean end-of-string only.+ const match = /(?:^|\n)##\s+Raw\s*\n+([\s\S]*?)\s*$/.exec(body);+ if (!match) return undefined;+ const raw = match[1]?.trim();+ if (!raw || raw === "_(not provided)_") return undefined;+ return raw;+}++function requireField(meta: Record<string, unknown>, field: string): void {+ if (!(field in meta) || meta[field] === undefined || meta[field] === null) {+ throw new Error(`signal missing field: ${field}`);+ }+ if (typeof meta[field] === "string" && (meta[field] as string).trim() === "") {+ throw new Error(`signal missing field: ${field}`);+ }+}++function requireString(meta: Record<string, unknown>, field: string): string {+ requireField(meta, field);+ const v = meta[field];+ if (typeof v !== "string") {+ throw new Error(`signal field '${field}' must be a string`);+ }+ return v;+}++function requireStringArray(+ meta: Record<string, unknown>,+ field: string,+): ReadonlyArray<string> {+ requireField(meta, field);+ const v = meta[field];+ if (!Array.isArray(v)) {+ throw new Error(`signal field '${field}' must be an array`);+ }+ for (const item of v) {+ if (typeof item !== "string") {+ throw new Error(+ `signal field '${field}' must be an array of strings`,+ );+ }+ }+ return [...(v as ReadonlyArray<string>)];+}diff --git a/src/core/brain/snapshot.ts b/src/core/brain/snapshot.tsnew file mode 100644index 00000000..2391ce09--- /dev/null+++ b/src/core/brain/snapshot.ts@@ -0,0 +1,616 @@+/**+ * Pre-`dream` snapshot, rotation, and rollback support.+ *+ * The contract (design doc Β§7.4 "Pre-run snapshot" + Β§15 Step 9a):+ *+ * - Before any state-changing operation in a `dream` run we write+ * `Brain/.snapshots/<run_id>.tar.zst` containing the entire+ * `Brain/` tree **excluding** `Brain/.snapshots/` itself.+ * Including the snapshots dir would either explode the archive or+ * racy-clobber an in-progress write.+ *+ * - Retention is enforced by `pruneSnapshots`: keep the+ * `snapshots.retention_count` newest files, delete the rest.+ *+ * - `restoreSnapshot` extracts the archive over `Brain/`. Critical+ * constraint: the restore must NOT touch `Brain/.snapshots/`,+ * otherwise rolling back to an older state could destroy newer+ * snapshots (and with them the user's only path forward again).+ * We achieve this by extracting into a sibling temp directory,+ * verifying the contents, then replacing every top-level entry+ * under `Brain/` *except* `.snapshots/`.+ *+ * - Tooling: we shell out to system `tar` and `zstd`. Both are+ * ubiquitous on the deployment surface (Linux server, macOS dev+ * workstations, every shared CI runner). Falling back to gzip+ * when `zstd` is absent keeps the feature usable on minimal+ * containers; falling back to nothing when `tar` is absent throws+ * {@link BrainSnapshotToolingMissingError} with an actionable+ * message.+ *+ * No external dependencies. Everything is `node:child_process` ++ * `node:fs` so the cost is one subprocess per archive operation.+ */++import { spawnSync } from "node:child_process";+import {+ closeSync,+ cpSync,+ existsSync,+ mkdirSync,+ mkdtempSync,+ openSync,+ readSync,+ readdirSync,+ rmSync,+ statSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { basename, join } from "node:path";++import { brainDirs, snapshotPath, validateRunId } from "./paths.ts";++// ----- Errors ---------------------------------------------------------------++/**+ * Thrown when the host lacks both `tar` and any compressor we know how+ * to use. Distinct from `BrainSnapshotError` so callers can pattern-+ * match and offer install instructions.+ */+export class BrainSnapshotToolingMissingError extends Error {+ constructor(tool: string, hint: string) {+ super(+ `snapshot tooling missing: '${tool}' not found on PATH. ${hint}`,+ );+ this.name = "BrainSnapshotToolingMissingError";+ }+}++/**+ * Generic snapshot failure (archive write failed, restore failed,+ * archive contents corrupted). Includes the runId in the message so+ * the operator can locate it.+ */+export class BrainSnapshotError extends Error {+ readonly runId: string;+ constructor(message: string, runId: string) {+ super(`snapshot[${runId}]: ${message}`);+ this.name = "BrainSnapshotError";+ this.runId = runId;+ }+}++// ----- Types ---------------------------------------------------------------++export interface CreateSnapshotResult {+ /** Absolute path of the resulting archive. */+ readonly path: string;+}++export interface SnapshotInfo {+ readonly run_id: string;+ readonly path: string;+ /** ISO-8601 UTC mtime of the archive file. */+ readonly created_at: string;+ readonly size_bytes: number;+}++export interface PruneSnapshotsResult {+ /** Vault-relative path of each deleted archive. */+ readonly deleted: ReadonlyArray<string>;+}++export interface RestoreSnapshotResult {+ /** Number of regular files restored under `Brain/` (excluding `.snapshots/`). */+ readonly restored_files: number;+}++// ----- Tooling detection ---------------------------------------------------++interface ToolAvailability {+ readonly tar: boolean;+ readonly zstd: boolean;+ readonly gzip: boolean;+}++/**+ * Detect tool availability by walking `process.env.PATH` and checking+ * the candidate binary exists. We deliberately avoid `spawnSync(cmd,+ * ["--version"])` because the underlying Node/Bun runtime resolves+ * commands against an internal PATH snapshot taken at process start+ * β so tests that mutate `process.env.PATH` between calls would have+ * no effect on a `spawnSync` probe. Reading the filesystem at probe+ * time keeps the detection honest and test-controllable.+ *+ * The cost (a handful of `existsSync` calls) is dwarfed by the actual+ * archive operation that follows.+ */+function detectTooling(): ToolAvailability {+ const pathEnv = process.env["PATH"] ?? "";+ const dirs = pathEnv.split(":").filter((d) => d.length > 0);+ const probe = (cmd: string): boolean => {+ for (const d of dirs) {+ if (existsSync(join(d, cmd))) return true;+ }+ return false;+ };+ return {+ tar: probe("tar"),+ zstd: probe("zstd"),+ gzip: probe("gzip"),+ };+}++// ----- createSnapshot ------------------------------------------------------++/**+ * Archive `Brain/` (except `.snapshots/`) into+ * `Brain/.snapshots/<run_id>.tar.zst`.+ *+ * Implementation:+ *+ * 1. Detect available tools. If `tar` is absent we throw.+ * 2. List the top-level entries under `Brain/`, drop `.snapshots/`.+ * 3. `tar -c -C <vault> Brain/<entry> ...` streamed into `zstd -19`+ * (or `gzip -9` fallback) β output file.+ *+ * Using `--exclude=Brain/.snapshots` is tempting, but tar's exclude+ * pattern matching is shell-dependent and prone to subtle surprises+ * on filenames containing whitespace. Enumerating the kept entries+ * explicitly is byte-stable and easy to reason about.+ */+export function createSnapshot(+ vault: string,+ runId: string,+): CreateSnapshotResult {+ validateRunId(runId);+ const dirs = brainDirs(vault);+ mkdirSync(dirs.snapshots, { recursive: true });++ const outPath = snapshotPath(vault, runId);+ const tools = detectTooling();+ if (!tools.tar) {+ throw new BrainSnapshotToolingMissingError(+ "tar",+ "install GNU tar or BSD tar; both are supported.",+ );+ }++ // List top-level entries of Brain/ that we want to capture. Sort the+ // result so the resulting archive's contents are deterministic+ // across filesystems (readdirSync's order is FS-dependent).+ let topEntries: string[];+ try {+ topEntries = readdirSync(dirs.brain).filter((e) => e !== ".snapshots");+ } catch (err) {+ throw new BrainSnapshotError(+ `failed to list Brain/: ${(err as Error).message ?? String(err)}`,+ runId,+ );+ }+ topEntries.sort();+ if (topEntries.length === 0) {+ // No content to archive. Tar would still produce an empty archive,+ // which is fine β `restoreSnapshot` on an empty archive is a no-op+ // that doesn't delete anything (because the exclude-`.snapshots`+ // rule keeps the dir intact).+ }++ // Build `tar -c -C <vault> Brain/<entry> Brain/<entry>...` so paths+ // inside the archive start at `Brain/` β matching the rollback+ // contract that the archive is "the Brain/ tree".+ const tarArgs = ["-c", "-C", vault, "--", ...topEntries.map((e) => `Brain/${e}`)];++ if (tools.zstd) {+ runArchivePipeline(["tar", tarArgs], ["zstd", ["-19", "-q", "-o", outPath, "-"]], runId);+ } else if (tools.gzip) {+ // Same on-disk extension keeps the snapshot listing logic+ // homogeneous. The contents are gzip-compressed regardless; the+ // restore probes both compressors so this is safe.+ runArchivePipeline(["tar", tarArgs], ["gzip", ["-9", "-c"]], runId, outPath);+ } else {+ throw new BrainSnapshotToolingMissingError(+ "zstd or gzip",+ "install zstd (preferred) or gzip; we use the first available.",+ );+ }++ if (!existsSync(outPath)) {+ throw new BrainSnapshotError(+ `archive write reported success but ${outPath} is absent`,+ runId,+ );+ }+ return { path: outPath };+}++/**+ * Run `producer | consumer` synchronously. On Linux `spawnSync`+ * supports a `stdio` pipe between two processes via the `input` field+ * β but we want a streaming pipe, not a full-buffer round-trip, since+ * the Brain tree could in principle exceed available memory. Use+ * `sh -c '<cmd1> | <cmd2>'` so the shell wires the pipe directly.+ *+ * Argument quoting: we deliberately do NOT shell-escape paths because+ * `tar -C <vault>` already roots everything relative to the vault,+ * and the only user-supplied bytes in `tarArgs` are the run id (which+ * `validateRunId` constrains to `[A-Za-z0-9._-]`) and the top-level+ * Brain/ entries (`inbox`, `preferences`, β¦) which are themselves+ * filesystem names produced by our own writers.+ *+ * For full safety against any future caller pattern, callers can+ * audit `tarArgs` to confirm no unconstrained user input lands here.+ */+function runArchivePipeline(+ producer: readonly [string, ReadonlyArray<string>],+ consumer: readonly [string, ReadonlyArray<string>],+ runId: string,+ outPath?: string,+): void {+ // We avoid shell pipe entirely: spawn the producer, capture its+ // stdout into a Buffer (acceptable: Brain trees are small β+ // typical compressed output is well under 1 MB per the design+ // doc), then feed it to the consumer's stdin synchronously.+ //+ // The previous approach used `sh -c "tar ... | zstd ..."` and broke+ // on quoting of paths with whitespace. Buffering through Node is+ // simpler and verifiably correct.+ const [prodCmd, prodArgs] = producer;+ const tarResult = spawnSync(prodCmd, [...prodArgs], {+ maxBuffer: 256 * 1024 * 1024, // 256 MB hard ceiling matches the design's "small" guarantee.+ stdio: ["ignore", "pipe", "pipe"],+ });+ if (tarResult.error) {+ throw new BrainSnapshotError(+ `${prodCmd} failed to start: ${tarResult.error.message}`,+ runId,+ );+ }+ if (tarResult.status !== 0) {+ const stderr = (tarResult.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `${prodCmd} exited with status ${tarResult.status}: ${stderr}`,+ runId,+ );+ }+ const tarPayload = tarResult.stdout;+ if (!tarPayload) {+ throw new BrainSnapshotError(`${prodCmd} produced no stdout`, runId);+ }++ const [consCmd, consArgs] = consumer;+ // `zstd -o <out>` opens the file itself; gzip writes to stdout and+ // we pipe to file via `outPath`.+ if (outPath === undefined) {+ const r = spawnSync(consCmd, [...consArgs], {+ input: tarPayload,+ stdio: ["pipe", "inherit", "pipe"],+ });+ if (r.error) {+ throw new BrainSnapshotError(+ `${consCmd} failed to start: ${r.error.message}`,+ runId,+ );+ }+ if (r.status !== 0) {+ const stderr = (r.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `${consCmd} exited with status ${r.status}: ${stderr}`,+ runId,+ );+ }+ } else {+ // gzip pipeline β capture stdout, write to file.+ const r = spawnSync(consCmd, [...consArgs], {+ input: tarPayload,+ stdio: ["pipe", "pipe", "pipe"],+ maxBuffer: 256 * 1024 * 1024,+ });+ if (r.error) {+ throw new BrainSnapshotError(+ `${consCmd} failed to start: ${r.error.message}`,+ runId,+ );+ }+ if (r.status !== 0) {+ const stderr = (r.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `${consCmd} exited with status ${r.status}: ${stderr}`,+ runId,+ );+ }+ // Write the compressed payload to the snapshot file atomically.+ // Use writeFileSync since the file is binary and lives inside+ // `.snapshots/` (no Markdown parser cares about torn writes here;+ // worst case is a corrupt archive that fails on restore β same+ // outcome as any other interrupted snapshot).+ writeFileSync(outPath, r.stdout ?? Buffer.from(""));+ }+}++// ----- listSnapshots / pruneSnapshots --------------------------------------++/**+ * Enumerate `.snapshots/*.tar.zst` in newest-first order (by mtime).+ * Files outside the canonical naming pattern are silently skipped so+ * a stray text file in the dir doesn't poison the listing.+ */+export function listSnapshots(vault: string): SnapshotInfo[] {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.snapshots)) return [];+ let entries: string[];+ try {+ entries = readdirSync(dirs.snapshots);+ } catch {+ return [];+ }+ const infos: SnapshotInfo[] = [];+ for (const name of entries) {+ if (!name.endsWith(".tar.zst")) continue;+ const runId = name.slice(0, -".tar.zst".length);+ // The `.snapshots/` dir is ours, so a malformed run_id here would+ // indicate manual tampering β we keep the listing tolerant and+ // skip rather than throw.+ try {+ validateRunId(runId);+ } catch {+ continue;+ }+ const full = join(dirs.snapshots, name);+ let st;+ try {+ st = statSync(full);+ } catch {+ continue;+ }+ infos.push({+ run_id: runId,+ path: full,+ created_at: new Date(st.mtimeMs).toISOString(),+ size_bytes: st.size,+ });+ }+ // Sort newest-first by mtime. We deliberately avoid lexicographic+ // sort on the run_id because manual rollback runs might use a+ // non-timestamped id and we still want them to land where the+ // operator's mental model expects (most recent first).+ infos.sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at));+ return infos;+}++/**+ * Delete all but the `retention_count` newest archives. Returns the+ * paths that were deleted, vault-relative. Idempotent β a second run+ * on the same dir returns `deleted: []`.+ */+export function pruneSnapshots(+ vault: string,+ retentionCount: number,+): PruneSnapshotsResult {+ if (!Number.isInteger(retentionCount) || retentionCount < 0) {+ throw new Error(+ `pruneSnapshots: retentionCount must be a non-negative integer; got ${retentionCount}`,+ );+ }+ const all = listSnapshots(vault);+ if (all.length <= retentionCount) {+ return { deleted: [] };+ }+ const victims = all.slice(retentionCount);+ const deleted: string[] = [];+ for (const v of victims) {+ try {+ rmSync(v.path, { force: true });+ deleted.push(v.path);+ } catch {+ // Best-effort: a snapshot we can't delete (permission error)+ // stays put. The next dream run will try again.+ }+ }+ return { deleted };+}++// ----- restoreSnapshot -----------------------------------------------------++/**+ * Restore the archive identified by `runId` over `Brain/`. The current+ * `.snapshots/` directory is preserved verbatim so older rollbacks+ * still have a path back.+ *+ * Steps:+ *+ * 1. Locate the archive.+ * 2. Extract into a sibling temp dir.+ * 3. Verify the extracted tree contains a `Brain/` root.+ * 4. For each top-level entry under the extracted `Brain/` (which+ * excludes `.snapshots/` by virtue of how the archive was+ * written), remove the corresponding live entry and copy the+ * extracted one into place.+ * 5. Clean up the temp dir.+ */+export function restoreSnapshot(+ vault: string,+ runId: string,+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for future log emission+ _opts: { now?: Date } = {},+): RestoreSnapshotResult {+ validateRunId(runId);+ const archive = snapshotPath(vault, runId);+ if (!existsSync(archive)) {+ throw new BrainSnapshotError(`archive does not exist: ${archive}`, runId);+ }+ const tools = detectTooling();+ if (!tools.tar) {+ throw new BrainSnapshotToolingMissingError(+ "tar",+ "install GNU tar or BSD tar; both support the same -x command.",+ );+ }++ const dirs = brainDirs(vault);+ const tmp = mkdtempSync(join(tmpdir(), `o2b-brain-restore-${runId}-`));+ try {+ // Probe the magic bytes to decide how to decompress. zstd starts+ // with `28 B5 2F FD`; gzip with `1F 8B`. Anything else is rejected+ // β we don't blindly try every decompressor.+ const decompressor = detectArchiveCompression(archive);+ if (decompressor === "zstd" && !tools.zstd) {+ throw new BrainSnapshotToolingMissingError(+ "zstd",+ "archive is zstd-compressed; install zstd to restore it.",+ );+ }+ if (decompressor === "gzip" && !tools.gzip) {+ throw new BrainSnapshotToolingMissingError(+ "gzip",+ "archive is gzip-compressed; install gzip to restore it.",+ );+ }++ if (decompressor === "zstd") {+ // Use shell pipe-free composition: zstd writes tar bytes to+ // stdout; we feed them into tar via stdin.+ const zstd = spawnSync("zstd", ["-d", "-c", archive], {+ maxBuffer: 256 * 1024 * 1024,+ stdio: ["ignore", "pipe", "pipe"],+ });+ if (zstd.error || zstd.status !== 0) {+ const stderr = (zstd.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `zstd decompress failed: ${zstd.error?.message ?? stderr}`,+ runId,+ );+ }+ const tar = spawnSync("tar", ["-x", "-C", tmp], {+ input: zstd.stdout,+ stdio: ["pipe", "inherit", "pipe"],+ });+ if (tar.error || tar.status !== 0) {+ const stderr = (tar.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `tar extract failed: ${tar.error?.message ?? stderr}`,+ runId,+ );+ }+ } else {+ // gzip route β let tar do the decompression directly via `-z`.+ const tar = spawnSync("tar", ["-x", "-z", "-f", archive, "-C", tmp], {+ stdio: ["ignore", "inherit", "pipe"],+ });+ if (tar.error || tar.status !== 0) {+ const stderr = (tar.stderr ?? Buffer.from("")).toString("utf8").trim();+ throw new BrainSnapshotError(+ `tar extract failed: ${tar.error?.message ?? stderr}`,+ runId,+ );+ }+ }++ // The extracted layout must contain a top-level `Brain/`. If the+ // archive was written from outside the design (e.g. someone+ // manually placed an unrelated `.tar.zst` in `.snapshots/`), we+ // refuse to proceed rather than scattering files.+ const extractedBrain = join(tmp, "Brain");+ if (!existsSync(extractedBrain)) {+ throw new BrainSnapshotError(+ "archive does not contain a Brain/ root",+ runId,+ );+ }++ // Replace every top-level entry under Brain/, EXCEPT `.snapshots/`.+ // The exclusion is the load-bearing safety guarantee: rolling back+ // an older state must not erase newer snapshots, otherwise the+ // operator is one click away from losing their forward path.+ const replacementEntries = readdirSync(extractedBrain).filter(+ (e) => e !== ".snapshots",+ );++ // First, remove top-level entries under live Brain/ that are NOT+ // `.snapshots/` and ARE present in the snapshot. (We do not delete+ // entries unique to the live tree β that would be a stronger+ // semantic than "restore", since restore should converge the live+ // tree to the snapshot.) Actually the correct semantics ARE+ // "live tree == snapshot tree minus .snapshots/". So we delete+ // every live top-level entry except `.snapshots/`, then copy in+ // from the extracted Brain/. This makes restore deterministic.+ const liveEntries = existsSync(dirs.brain)+ ? readdirSync(dirs.brain).filter((e) => e !== ".snapshots")+ : [];+ for (const name of liveEntries) {+ const target = join(dirs.brain, name);+ try {+ rmSync(target, { recursive: true, force: true });+ } catch (err) {+ throw new BrainSnapshotError(+ `failed to remove live entry ${name}: ${(err as Error).message ?? String(err)}`,+ runId,+ );+ }+ }+ // Copy in each extracted entry. `cpSync({ recursive: true })` is+ // available in Node 18+ and Bun, which is the target runtime.+ let restoredFiles = 0;+ mkdirSync(dirs.brain, { recursive: true });+ for (const name of replacementEntries) {+ const from = join(extractedBrain, name);+ const to = join(dirs.brain, name);+ cpSync(from, to, { recursive: true });+ restoredFiles += countFiles(to);+ }+ return { restored_files: restoredFiles };+ } finally {+ try {+ rmSync(tmp, { recursive: true, force: true });+ } catch {+ // tmp cleanup is best-effort; the OS will reclaim it eventually.+ }+ }+}++// ----- Helpers -------------------------------------------------------------++function detectArchiveCompression(archive: string): "zstd" | "gzip" {+ const buf = Buffer.alloc(4);+ const fd = openSync(archive, "r");+ try {+ readSync(fd, buf, 0, 4, 0);+ } finally {+ closeSync(fd);+ }+ // zstd magic: 0x28 0xB5 0x2F 0xFD (little-endian view of 0xFD2FB528).+ if (buf[0] === 0x28 && buf[1] === 0xb5 && buf[2] === 0x2f && buf[3] === 0xfd) {+ return "zstd";+ }+ // gzip magic: 0x1F 0x8B+ if (buf[0] === 0x1f && buf[1] === 0x8b) {+ return "gzip";+ }+ // Default to zstd since that's our preferred writer β restore will+ // fail loudly through the zstd subprocess if the bytes don't match.+ return "zstd";+}++function countFiles(path: string): number {+ try {+ const st = statSync(path);+ if (st.isFile()) return 1;+ if (!st.isDirectory()) return 0;+ } catch {+ return 0;+ }+ let count = 0;+ for (const entry of readdirSync(path, { withFileTypes: true })) {+ const sub = join(path, entry.name);+ if (entry.isDirectory()) {+ count += countFiles(sub);+ } else if (entry.isFile()) {+ count++;+ }+ }+ return count;+}++// Silence unused-symbol lints for helpers exported only via re-export.+void basename;diff --git a/src/core/brain/templates/_BRAIN.md.tpl b/src/core/brain/templates/_BRAIN.md.tplnew file mode 100644index 00000000..72aaace0--- /dev/null+++ b/src/core/brain/templates/_BRAIN.md.tpl@@ -0,0 +1,153 @@+---+kind: brain-manual+vault_name: {{vault_name}}+schema_version: {{schema_version}}+---++# Brain β operating manual++Brain is the observing-memory layer of Open Second Brain. It records what+the user likes and dislikes by watching what they accept and reject, then+distils that into rules the next agent session can read and apply.++Read this file at the start of every session that may write to the vault.+Cross-reference: `Projects/OpenSecondBrain/Plan` if the vault carries the+design notes.++## Layout++```+Brain/+ _brain.yaml # configuration; hand-editable+ _BRAIN.md # this file+ inbox/ # raw signals captured during work+ processed/ # signals already folded into a preference+ preferences/ # active rules (unconfirmed or confirmed)+ retired/ # superseded / expired / rebutted / rejected rules+ log/ # daily ledger of every state change+ .snapshots/ # pre-`dream` archives for rollback+```++The directory a note sits in encodes its lifecycle state. The frontmatter+`status` field duplicates it for convenience. `o2b brain doctor` reports+mismatches.++## Lifecycle of one preference++```+inbox/sig-* dream unconfirmed+ (taste signal) ββββΊ (cluster) ββββΊ preferences/pref-*+ β+ apply-evidence (applied) ββββββ€+ βΌ+ confirmed+ β+ no evidence within window ββββββββΊβ+ rebuttal signals reach threshold ββ€+ stale_evidence_days passed βββββββΊβ+ o2b brain reject βββββββββββββββββΊβΌ+ retired/ret-*+```++Promotion happens automatically when N positive same-topic signals+accumulate (`_brain.yaml: dream.candidate_threshold`, default 3). First+real-work application flips a preference from `unconfirmed` to+`confirmed`. No human approval step exists in the default loop.++## When to call `brain_feedback`++After a taste signal β the user accepted or rejected a stylistic choice,+a structural decision, a tone, a naming convention.++- Sign: `positive` (user liked it) or `negative` (user pushed back).+- `topic` is the dedup anchor: same `topic` accumulates toward promotion.+ Pick a stable, hyphenated slug (`no-internal-abbrev`, not `abbreviations`).+- `principle` is one short imperative sentence β what rule should emerge.+- Skip pure preferences with no action attached, idle banter, and+ repeated agreement on a topic that already has an active preference+ (the next `dream` run notes the redundancy automatically).++## When to call `brain_apply_evidence`++After producing a durable artifact whose form was governed by an active+preference. Two outcomes:++- `applied` β the artifact followed the rule.+- `violated` β the artifact contradicted it (rare, but record it; the+ log keeps both columns).++The `preference` argument is the wikilink target (`pref-no-internal-abbrev`),+the `artifact` argument is the wikilink to the produced note / file /+PR / message. Confirmation, confidence, and retire eligibility are+recomputed by the next `dream` run from log evidence β there is no+separate "promote" call.++Apply-evidence is only meaningful for `confirmed` preferences and for+`unconfirmed` ones that the artifact actually exercised. Stay quiet+otherwise β noise drowns the signal.++## `dream` β the batch pass++`dream` is the one mutating operation. It is deterministic given inputs+and `--now`. It:++- groups signals by topic, promotes those that cross the threshold;+- recomputes `applied_count` / `violated_count` / `last_evidence_at`+ from `log/`;+- flips first-applied unconfirmed prefs to confirmed;+- retires expired, stale, rebutted, or user-rejected prefs;+- moves consumed signals into `inbox/processed/`;+- archives Brain into `.snapshots/<run_id>.tar.zst` before mutating;+- appends one summary entry to `log/<today>.md` if anything changed.++Rerunning `dream` without new inputs is a no-op (including in the log).+Schedule it on a cron with confidence β duplicate runs do not pollute.++## What NOT to do++- Do not hand-edit files under `log/` β they are append-only ledgers.+ `dream`, `apply-evidence`, `feedback`, and the CLI escape hatches are+ the only writers.+- Do not rename preference or signal files. The `id` field is duplicated+ in frontmatter to survive `mv`, but slugs are stable for a reason;+ changing them breaks every wikilink and every log reference.+- Do not write into `.snapshots/`. `dream` produces archives there;+ `o2b brain rollback` consumes them; nothing else touches the directory.+- Do not edit files in `retired/` to undo a retirement. The reason is+ preserved on purpose; a rule that should return becomes a new+ preference with `supersedes: [[ret-...]]`.+- Do not write into `AI Wiki/` or `Daily/` through Brain tools. Those+ layers serve different purposes (curated wiki / event log) and Brain+ operations stay scoped to `Brain/`. Pay Memory is the dedicated+ writer of `AI Wiki/payments/` and `AI Wiki/assets/`.+- Do not invent topics. Reuse an existing topic slug if the rule space+ is the same; `dream` collapses near-duplicates only by exact match.++## Escape hatches++These are CLI-only, intended for rare manual intervention. Do not call+them as part of normal agent work.++- `o2b brain reject <pref-id>` β explicit user-driven retirement. Moves+ the preference to `retired/` with reason `user-rejected`. A pinned+ preference requires `--yes` and prints a warning.+- `o2b brain rollback <run_id>` β restore Brain from a snapshot.+ Interactive by default; `--list` enumerates available snapshots.+- `o2b brain pin <pref-id>` / `unpin <pref-id>` β protect a preference+ from automatic retirement (still subject to explicit reject).++The full CLI surface is documented in `docs/plans/2026-05-15-brain-observing-memory.md`+section 9; the MCP tool surface mirrors it for the most common verbs+(`brain_feedback`, `brain_apply_evidence`, `brain_dream`, `brain_digest`,+`brain_query`, `brain_doctor`).++## Reading order for a new agent++1. This file (`Brain/_BRAIN.md`).+2. `Brain/_brain.yaml` for threshold values currently in effect.+3. `Brain/preferences/` for active rules; `confirmed` first, then+ `unconfirmed` (in trial).+4. `Brain/retired/` only when checking why a rule no longer applies.++Brain is filesystem-first. A `cp -r Brain/` is a complete backup; a+`git diff` shows the exact state delta. Trust the files.diff --git a/src/core/brain/templates/_OPEN_SECOND_BRAIN.md.tpl b/src/core/brain/templates/_OPEN_SECOND_BRAIN.md.tplnew file mode 100644index 00000000..9b8e95ff--- /dev/null+++ b/src/core/brain/templates/_OPEN_SECOND_BRAIN.md.tpl@@ -0,0 +1,63 @@+---+open_second_brain_version: 1+layer: brain-first+---++# Open Second Brain β vault overview++This vault is managed by Open Second Brain. The vault holds three+top-level agent-facing directories, each with a distinct purpose.++## Layers++- **`Brain/`** β observing memory. Signals, preferences, retired+ rules, log, snapshots. Mutated only through `o2b brain *` commands+ and the `brain_*` MCP tools. The full operating manual lives at+ `Brain/_BRAIN.md` β read it before any Brain operation.++- **`AI Wiki/`** β curated knowledge surface. Identity files+ (`identity/`), index and hot list, system snapshots, and the Pay+ Memory subtree (`payments/`, `assets/`, `drafts/`, `reports/`,+ `policies/`). Agents read it via `second_brain_query` and write+ into the Pay Memory subtree via the `payment_*` MCP tools; they+ do not otherwise mutate this area through Brain tools.++- **`Daily/`** β chronological event log and human narrative.+ Visible to `second_brain_query` for cross-referencing past+ activity; Brain operations do not write here.++## Where agents write++- Taste signals and rule applications go through Brain: call+ `brain_feedback` after a stylistic accept/reject, call+ `brain_apply_evidence` after a durable artifact that exercised an+ active preference, and let `brain_dream` (scheduled or manual)+ promote, confirm, and retire rules from that evidence.++- Paid actions go through Pay Memory. `AI Wiki/payments/`,+ `AI Wiki/assets/`, and the spending policy at+ `AI Wiki/policies/spending.json` remain the audit surface for any+ call that costs money. Pay Memory is orthogonal to Brain β both+ layers coexist on the same vault without overlap.++## Where agents read++`second_brain_query` covers the whole vault. Use it to recall an+`AI Wiki/` note, look up a `Daily/` entry, or surface a specific+Brain preference by id. Read-only.++## Conventions++- All notes are Markdown with YAML frontmatter. No databases, no+ daemons. `cp -r` is a full backup.+- Cross-references are Obsidian wikilinks (`[[basename]]`). No+ relative paths.+- Never write secrets, tokens, or credentials into any file.++## Quick start++1. Read `Brain/_BRAIN.md` β the operating manual for the writable layer.+2. Read `AI Wiki/identity/user.md` and `AI Wiki/identity/agents.md` β+ who owns the vault and which agents are registered.+3. When in doubt about a Brain command, see+ `docs/plans/2026-05-15-brain-observing-memory.md` in the repo.diff --git a/src/core/brain/time.ts b/src/core/brain/time.tsnew file mode 100644index 00000000..933168f3--- /dev/null+++ b/src/core/brain/time.ts@@ -0,0 +1,27 @@+/**+ * Time helpers for the Brain layer.+ *+ * Both functions emit canonical UTC strings expected by the on-disk+ * formats (frontmatter, log headings, run ids):+ *+ * - `isoSecond` β `YYYY-MM-DDTHH:MM:SSZ` (no sub-second precision).+ * The log heading shape is `HH:MM:SS` only, so anything finer is+ * silently dropped by `appendLogEvent`; truncating here keeps the+ * return value consistent with what actually lands on disk.+ * - `isoDate` β `YYYY-MM-DD` (UTC calendar day).+ *+ * Both default to `new Date()` so callers can do `isoSecond()` without+ * threading the clock when they don't need determinism.+ */++/** ISO-8601 UTC at whole-second precision (`YYYY-MM-DDTHH:MM:SSZ`). */+export function isoSecond(d: Date = new Date()): string {+ // `Date#toISOString` always emits `YYYY-MM-DDTHH:MM:SS.sssZ`; strip+ // the milliseconds segment in-place to land on the canonical shape.+ return d.toISOString().replace(/\.\d{3}Z$/, "Z");+}++/** ISO-8601 UTC calendar day (`YYYY-MM-DD`). */+export function isoDate(d: Date = new Date()): string {+ return d.toISOString().slice(0, 10);+}diff --git a/src/core/brain/types.ts b/src/core/brain/types.tsnew file mode 100644index 00000000..fef15064--- /dev/null+++ b/src/core/brain/types.ts@@ -0,0 +1,357 @@+/**+ * Type definitions for the Brain observing-memory layer.+ *+ * These are plain data shapes β no behaviour, no I/O. They describe the+ * frontmatter contracts of every Brain artifact (signal, preference,+ * retired, log entry) plus the schema of `_brain.yaml`. Parsers and+ * writers (added in Task 2) produce and consume these shapes; the dream+ * algorithm (Task 3) operates on collections of them.+ *+ * Anchored in `docs/plans/2026-05-15-brain-observing-memory.md`,+ * sections 5 (file formats) and 10 (configuration).+ */++// ----- Status & retire-reason enums -----------------------------------------+//+// We use `as const` objects with derived union types instead of TypeScript+// `enum` declarations. `enum` does not interoperate well with+// `verbatimModuleSyntax: true` (which this repo enables) and the+// `as const` form survives type-only re-exports cleanly.++export const BRAIN_SIGNAL_SIGN = {+ positive: "positive",+ negative: "negative",+} as const;+export type BrainSignalSign =+ (typeof BRAIN_SIGNAL_SIGN)[keyof typeof BRAIN_SIGNAL_SIGN];++export const BRAIN_PREFERENCE_STATUS = {+ unconfirmed: "unconfirmed",+ confirmed: "confirmed",+} as const;+export type BrainPreferenceStatus =+ (typeof BRAIN_PREFERENCE_STATUS)[keyof typeof BRAIN_PREFERENCE_STATUS];++export const BRAIN_CONFIDENCE = {+ low: "low",+ medium: "medium",+ high: "high",+} as const;+export type BrainConfidence =+ (typeof BRAIN_CONFIDENCE)[keyof typeof BRAIN_CONFIDENCE];++export const BRAIN_RETIRED_REASON = {+ staleNoEvidence: "stale-no-evidence",+ expiredUnconfirmed: "expired-unconfirmed",+ rebutted: "rebutted",+ userRejected: "user-rejected",+} as const;+export type BrainRetiredReason =+ (typeof BRAIN_RETIRED_REASON)[keyof typeof BRAIN_RETIRED_REASON];++export const BRAIN_APPLY_RESULT = {+ applied: "applied",+ violated: "violated",+} as const;+export type BrainApplyResult =+ (typeof BRAIN_APPLY_RESULT)[keyof typeof BRAIN_APPLY_RESULT];++/**+ * All possible log event types. `dream` summarises a run; `feedback`+ * records the creation of a signal; `apply-evidence` records a real-work+ * application; `force-confirmed` records a `--force-confirmed` flag use;+ * `reject` / `promote` / `retire` record the corresponding state+ * transitions; `noted-redundant` records same-sign signals collapsed onto+ * an active pref; `skip-corrupted-frontmatter` records files dream+ * skipped; `pin` / `unpin` record protected-set changes; `rollback`+ * records a snapshot restore. See Β§5.5 and Β§7.4 of the design doc.+ */+export const BRAIN_LOG_EVENT_KIND = {+ dream: "dream",+ feedback: "feedback",+ applyEvidence: "apply-evidence",+ forceConfirmed: "force-confirmed",+ reject: "reject",+ promote: "promote",+ retire: "retire",+ notedRedundant: "noted-redundant",+ skipCorruptedFrontmatter: "skip-corrupted-frontmatter",+ pin: "pin",+ unpin: "unpin",+ rollback: "rollback",+} as const;+export type BrainLogEventKind =+ (typeof BRAIN_LOG_EVENT_KIND)[keyof typeof BRAIN_LOG_EVENT_KIND];++// ----- File-frontmatter shapes ----------------------------------------------++/**+ * Raw taste signal (`Brain/inbox/sig-*.md`).+ *+ * Immutable after creation. Required fields are enforced at write time;+ * optional fields default per the design doc Β§5.2.+ */+export interface BrainSignal {+ readonly kind: "brain-signal";+ /** Filename basename without `.md`. Equals `sig-<date>-<slug>`. */+ readonly id: string;+ /** ISO-8601 UTC timestamp. */+ readonly created_at: string;+ /**+ * Includes `brain`, `brain/signal`, and per-topic / per-scope tags. The+ * parser preserves whatever the writer emitted; the writer guarantees+ * the canonical set.+ */+ readonly tags: ReadonlyArray<string>;+ /** Required dedup anchor for `dream`. */+ readonly topic: string;+ /** Optional soft category (e.g. `writing`, `coding`). */+ readonly scope?: string;+ /** Sign of the signal. */+ readonly signal: BrainSignalSign;+ /** Source agent or human name. */+ readonly agent: string;+ /** Optional wikilinks to context artifacts. */+ readonly source?: ReadonlyArray<string>;+ /**+ * One-line agent-readable formulation of the rule this signal points+ * toward. Carried into the resulting preference's `principle` when a+ * cluster of signals is promoted.+ */+ readonly principle: string;+ /** Optional free-form raw body following the frontmatter. */+ readonly raw?: string;+}++/**+ * Rule promoted from a cluster of signals (`Brain/preferences/pref-*.md`).+ *+ * Two states: `unconfirmed` (just promoted) and `confirmed` (applied at+ * least once in real work). Counter fields are computed by `dream` from+ * the log and rewritten on every run β never hand-edited.+ */+export interface BrainPreference {+ readonly kind: "brain-preference";+ /** Filename basename without `.md`. Equals `pref-<slug>`. */+ readonly id: string;+ /** ISO-8601 UTC timestamp of promotion. */+ readonly created_at: string;+ /** ISO-8601 UTC of first `applied` evidence; `null` while unconfirmed. */+ readonly confirmed_at: string | null;+ /** ISO-8601 UTC trial deadline (`created_at + unconfirmed_window_days`). */+ readonly unconfirmed_until: string;+ readonly tags: ReadonlyArray<string>;+ readonly topic: string;+ readonly scope?: string;+ readonly status: BrainPreferenceStatus;+ readonly principle: string;+ /** Origin signals; fixed at creation. Wikilinks (`[[sig-...]]`). */+ readonly evidenced_by: ReadonlyArray<string>;+ /** Computed from `Brain/log/`. */+ readonly applied_count: number;+ /** Computed from `Brain/log/`. */+ readonly violated_count: number;+ /** ISO-8601 UTC of most recent `apply-evidence` entry. */+ readonly last_evidence_at: string | null;+ readonly confidence: BrainConfidence;+ /**+ * If `true`, exempt from automatic retire reasons (`stale-no-evidence`,+ * `expired-unconfirmed`, `rebutted`). Defaults to `false` when a parsed+ * note lacks the field β parsers MUST coerce missing/`null`/`undefined`+ * to `false`.+ */+ readonly pinned: boolean;+ /** Optional wikilink to a retired pref this one replaces. */+ readonly supersedes?: string;+ readonly aliases?: ReadonlyArray<string>;+}++/**+ * Retired preference (`Brain/retired/ret-*.md`).+ *+ * Same identity slug as the originating preference; the prefix flips+ * from `pref-` to `ret-`. The frontmatter inherits the preference's+ * fields (topic, principle, evidenced_by, β¦) plus the retirement+ * metadata below.+ */+export interface BrainRetired {+ readonly kind: "brain-retired";+ /** Filename basename without `.md`. Equals `ret-<slug>`. */+ readonly id: string;+ readonly status: "retired";+ /** ISO-8601 UTC timestamp of the retire transition. */+ readonly retired_at: string;+ readonly retired_reason: BrainRetiredReason;+ /** Wikilink to the `dream` run (or CLI action) that retired it. */+ readonly retired_by: string;+ /** Optional wikilink to a newer preference that supersedes this one. */+ readonly superseded_by?: string;+ // ----- Inherited from the preference (snapshot at retire time) -----+ readonly created_at: string;+ readonly tags: ReadonlyArray<string>;+ readonly topic: string;+ readonly scope?: string;+ readonly principle: string;+ readonly evidenced_by: ReadonlyArray<string>;+ readonly applied_count: number;+ readonly violated_count: number;+ readonly last_evidence_at: string | null;+ readonly confidence: BrainConfidence;+ readonly pinned: boolean;+ readonly aliases?: ReadonlyArray<string>;+}++// ----- Log events -----------------------------------------------------------++/**+ * Common shape of every parsed log event. The `payload` map carries the+ * heading-specific key/value bullets verbatim (everything that follows+ * the `## <time> β <kind>` heading). Concrete event narrators consume+ * `payload` and translate it into typed views as needed.+ */+export interface BrainLogEventBase {+ readonly kind: BrainLogEventKind;+ /** ISO-8601 UTC timestamp reconstructed from `<YYYY-MM-DD>` + `HH:MM:SS`. */+ readonly at: string;+ /** Bullet payload of the event entry, key β string|string[] (lists). */+ readonly payload: Readonly<Record<string, string | ReadonlyArray<string>>>;+}++/** `dream` run summary entry. */+export interface BrainDreamLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.dream;+ readonly run_id: string;+}++/** `apply-evidence` entry β one application against a preference. */+export interface BrainApplyEvidenceLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.applyEvidence;+ /** Wikilink target of the preference, e.g. `pref-no-internal-abbrev`. */+ readonly preference: string;+ /** Wikilink of the artifact where the rule was applied. */+ readonly artifact: string;+ readonly agent: string;+ readonly result: BrainApplyResult;+ readonly note?: string;+}++/** `feedback` entry β new signal created. */+export interface BrainFeedbackLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.feedback;+ readonly signal: string;+ readonly topic: string;+ readonly sign: BrainSignalSign;+}++/** `force-confirmed` entry β `--force-confirmed` bypass. */+export interface BrainForceConfirmedLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.forceConfirmed;+ readonly preference: string;+ readonly agent: string;+}++/** `reject` entry β explicit user rejection. */+export interface BrainRejectLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.reject;+ readonly preference: string;+ readonly reason?: string;+}++/** `promote` entry β unconfirmed β confirmed transition. */+export interface BrainPromoteLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.promote;+ readonly preference: string;+}++/** `retire` entry β preference moved to `retired/`. */+export interface BrainRetireLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.retire;+ readonly preference: string;+ readonly reason: BrainRetiredReason;+}++/** `noted-redundant` entry β same-sign signal on an active pref. */+export interface BrainNotedRedundantLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.notedRedundant;+ readonly preference: string;+ readonly signal: string;+}++/** `skip-corrupted-frontmatter` β a file dream couldn't parse. */+export interface BrainSkipCorruptedLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.skipCorruptedFrontmatter;+ /** Vault-relative path of the offending file. */+ readonly path: string;+}++/** `pin` / `unpin` entry β protected-set change. */+export interface BrainPinLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.pin | typeof BRAIN_LOG_EVENT_KIND.unpin;+ readonly preference: string;+}++/** `rollback` entry β snapshot restored. */+export interface BrainRollbackLogEvent extends BrainLogEventBase {+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.rollback;+ readonly run_id: string;+}++/** Discriminated union of every concrete log event type. */+export type BrainLogEvent =+ | BrainDreamLogEvent+ | BrainApplyEvidenceLogEvent+ | BrainFeedbackLogEvent+ | BrainForceConfirmedLogEvent+ | BrainRejectLogEvent+ | BrainPromoteLogEvent+ | BrainRetireLogEvent+ | BrainNotedRedundantLogEvent+ | BrainSkipCorruptedLogEvent+ | BrainPinLogEvent+ | BrainRollbackLogEvent;++// ----- Configuration (`Brain/_brain.yaml`) ----------------------------------++export interface BrainDreamConfig {+ /** Minimum same-sign signal count to promote a topic. */+ readonly candidate_threshold: number;+ /** Days an unconfirmed preference may sit awaiting first application. */+ readonly unconfirmed_window_days: number;+ /** Window in which positive/negative signals cancel each other. */+ readonly contradiction_window_days: number;+}++export interface BrainRetireConfig {+ /** Days without evidence after which a confirmed pref retires. */+ readonly stale_evidence_days: number;+}++export interface BrainConfidenceConfig {+ /** `applied_count <= low_max_applied` β confidence `low`. */+ readonly low_max_applied: number;+ /** `applied_count >= high_min_applied` is required for `high`. */+ readonly high_min_applied: number;+ /**+ * Fresh-evidence factor: `now - last_evidence_at <+ * stale_evidence_days * high_freshness_factor`. Must be in `(0, 1]`.+ */+ readonly high_freshness_factor: number;+}++export interface BrainSnapshotsConfig {+ /** Keep this many newest `.snapshots/*.tar.zst`. Positive integer. */+ readonly retention_count: number;+}++/**+ * Root of `Brain/_brain.yaml`. `schema_version` is mandatory; unknown+ * top-level keys are tolerated as forward-compat (logged as a warning by+ * the validator, not an error).+ */+export interface BrainConfig {+ readonly schema_version: number;+ readonly dream: BrainDreamConfig;+ readonly retire: BrainRetireConfig;+ readonly confidence: BrainConfidenceConfig;+ readonly snapshots: BrainSnapshotsConfig;+}diff --git a/src/core/brain/wikilink.ts b/src/core/brain/wikilink.tsnew file mode 100644index 00000000..2bf345bc--- /dev/null+++ b/src/core/brain/wikilink.ts@@ -0,0 +1,77 @@+/**+ * Wikilink parsing helpers for the Brain layer.+ *+ * The Obsidian-flavoured wikilink shape is `[[target]]`, with optional+ * alias (`[[target|alias]]`) and anchor (`[[target#section]]`) suffixes.+ * Brain frontmatter writers always emit the bare `[[id]]` form, but the+ * parsers must tolerate the alias / anchor / folder-prefixed / `.md`-+ * suffixed variants because the on-disk artifacts are user-editable.+ *+ * Surface:+ *+ * - {@link normaliseWikilinkTarget} extracts the bare target id from+ * any of those shapes. Used by the doctor command (resolving+ * `evidenced_by` / `supersedes` pointers against the Brain index)+ * and by the query command (matching log payload values against a+ * preference id).+ *+ * - {@link parseWikilink} returns the target if the input is exactly+ * a wikilink form (`^\[\[β¦\]\]$`), or `null` otherwise. Used by the+ * dream loop's `evidenced_by` walker and the digest's tolerant+ * contradiction-line parser, where the caller wants to distinguish+ * "this is a wikilink" from "this is bare text".+ *+ * Both helpers are case-preserving and do NOT validate that the target+ * exists; that's a higher-layer concern (doctor cross-references against+ * the Brain index, dream relies on a follow-up `Map.has` check).+ */++import { basename } from "node:path";++/**+ * Strip wikilink decoration off `value` and return the bare target id.+ *+ * Recognises:+ * - surrounding `[[β¦]]` brackets (only the first match wins)+ * - `|alias` and `#anchor` suffixes (alias / anchor dropped)+ * - leading folder segments (`folder/foo` β `foo`)+ * - trailing `.md` extension+ *+ * Returns the input unchanged (minus a trim) when it isn't decorated;+ * callers can still distinguish bare text from "no input" via the empty+ * string.+ */+export function normaliseWikilinkTarget(value: string): string {+ let s = value.trim();+ // Strip surrounding wikilink brackets, retaining only the target.+ const wm = /^\[\[([^\]]+)\]\]/.exec(s);+ if (wm) s = wm[1]!.trim();+ // Drop alias / anchor suffixes (`foo|bar` or `foo#section`).+ const pipe = s.indexOf("|");+ if (pipe >= 0) s = s.slice(0, pipe).trim();+ const hash = s.indexOf("#");+ if (hash >= 0) s = s.slice(0, hash).trim();+ // Strip a leading folder if any (Obsidian links resolve by basename).+ s = basename(s);+ // Strip a trailing `.md` if the user supplied a filename.+ if (s.endsWith(".md")) s = s.slice(0, -".md".length);+ return s;+}++/**+ * Return the bare target id if `value` is exactly a wikilink form+ * (`^\[\[β¦\]\]$` modulo surrounding whitespace), otherwise `null`.+ *+ * Unlike {@link normaliseWikilinkTarget}, this is anchored: a bare id or+ * a mixed string ("see [[foo]]" embedded in prose) yields `null`. Use+ * this when "is this a wikilink at all?" is the question being asked.+ *+ * Alias / anchor / folder / `.md` decoration on the target itself is+ * stripped via the same logic as `normaliseWikilinkTarget` so callers+ * get a clean id either way.+ */+export function parseWikilink(value: string): string | null {+ const m = /^\s*\[\[([^\]]+)\]\]\s*$/.exec(value);+ if (!m) return null;+ return normaliseWikilinkTarget(m[1]!);+}diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsnew file mode 100644index 00000000..74f2684f--- /dev/null+++ b/src/mcp/brain-tools.ts@@ -0,0 +1,854 @@+/**+ * MCP tool registrations for the Brain layer.+ *+ * Exposes the six Brain operations that are safe to invoke from an+ * agent harness:+ *+ * - `brain_feedback` β record a single taste signal (or a+ * directly-confirmed preference when+ * `force_confirmed: true`).+ * - `brain_dream` β run the deterministic learning pass.+ * - `brain_apply_evidence` β record whether a preference was applied+ * or violated on a freshly-produced+ * artifact.+ * - `brain_digest` β render a human-readable summary of the+ * last activity window.+ * - `brain_query` β read-only aggregation by preference id,+ * topic, or time window.+ * - `brain_doctor` β invariant / schema health check.+ *+ * The five Brain commands that remain CLI-only on purpose+ * (`init`, `reject`, `pin`, `unpin`, `rollback`) deliberately do *not*+ * have MCP wrappers β see design doc Β§9.1 "absence from MCP protects+ * against autonomous mistakes". Their handler functions live in+ * `src/core/brain/*` and `src/cli/*` for shell-side use.+ *+ * Each handler delegates to the corresponding `src/core/brain/*`+ * function so the contract stays byte-identical to the CLI. Arguments+ * are coerced/validated locally with the same helpers the legacy tools+ * use; we re-implement the small ones here rather than re-exporting+ * private functions from `tools.ts` to keep the dependency direction+ * one-way (Brain tools may grow their own coercion rules later).+ */++import { existsSync } from "node:fs";+import { isAbsolute, relative, resolve } from "node:path";++import { resolveAgentName } from "../core/config.ts";+import {+ appendApplyEvidence,+ BrainPreferenceNotFoundError,+ type AppendApplyEvidenceInput,+} from "../core/brain/apply-evidence.ts";+import {+ renderDigest,+ type DigestFormat,+} from "../core/brain/digest.ts";+import { dream } from "../core/brain/dream.ts";+import { runDoctor } from "../core/brain/doctor.ts";+import {+ BrainNotFoundError,+ queryByLogSince,+ queryByPreference,+ queryByTopic,+} from "../core/brain/query.ts";+import { writeSignal } from "../core/brain/signal.ts";+import { writePreference } from "../core/brain/preference.ts";+import { preferencePath } from "../core/brain/paths.ts";+import { isoDate, isoSecond } from "../core/brain/time.ts";+import { loadBrainConfig } from "../core/brain/policy.ts";+import { slugify } from "../core/vault.ts";+import { normalizeAgentArgument } from "../core/agent-identity.ts";+import {+ BRAIN_LOG_EVENT_KIND,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_SIGNAL_SIGN,+ BRAIN_APPLY_RESULT,+ type BrainApplyResult,+ type BrainPreference,+ type BrainRetired,+ type BrainSignal,+ type BrainSignalSign,+} from "../core/brain/types.ts";+import { appendLogEvent } from "../core/brain/log.ts";+import type { BrainLogEntry } from "../core/brain/log.ts";++import { INVALID_PARAMS, MCPError } from "./protocol.ts";+import type { ServerContext, ToolDefinition } from "./tools.ts";++// ----- Local coercion helpers ----------------------------------------------+//+// Mirrors `tools.ts:coerceStr` family. We keep a private copy so the Brain+// tool module does not depend on the legacy `tools.ts` private API+// surface β the only shared types it imports are `ServerContext` and+// `ToolDefinition`.++function coerceStr(+ args: Record<string, unknown>,+ key: string,+ required = true,+ defaultValue: string | null = null,+): string | null {+ const value = args[key];+ if (+ value === undefined ||+ value === null ||+ (typeof value === "string" && value.trim() === "")+ ) {+ if (required) {+ throw new MCPError(INVALID_PARAMS, `missing required argument: ${key}`);+ }+ return defaultValue;+ }+ if (typeof value !== "string") {+ throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a string`);+ }+ return value;+}++function coerceStrList(+ args: Record<string, unknown>,+ key: string,+): string[] | null {+ const value = args[key];+ if (value === undefined || value === null) return null;+ if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {+ throw new MCPError(+ INVALID_PARAMS,+ `argument '${key}' must be a list of strings`,+ );+ }+ return [...value] as string[];+}++function coerceBool(+ args: Record<string, unknown>,+ key: string,+): boolean {+ const value = args[key];+ if (value === undefined || value === null) return false;+ if (typeof value !== "boolean") {+ throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a boolean`);+ }+ return value;+}++/**+ * Parse an optional ISO-8601 timestamp argument. Empty / missing β null.+ * Anything else must be a parseable date string; otherwise INVALID_PARAMS.+ */+function coerceIsoDate(+ args: Record<string, unknown>,+ key: string,+): Date | null {+ const raw = coerceStr(args, key, false);+ if (raw === null) return null;+ const d = new Date(raw);+ if (Number.isNaN(d.getTime())) {+ throw new MCPError(+ INVALID_PARAMS,+ `argument '${key}' must be a valid ISO-8601 timestamp`,+ );+ }+ return d;+}++/**+ * Coerce the optional `format` argument shared across digest / query /+ * doctor. Accepts `markdown` (default) or `json`. Anything else throws.+ */+function coerceFormat(+ args: Record<string, unknown>,+ key = "format",+): "markdown" | "json" {+ const raw = coerceStr(args, key, false);+ if (raw === null) return "markdown";+ if (raw !== "markdown" && raw !== "json") {+ throw new MCPError(+ INVALID_PARAMS,+ `argument '${key}' must be 'markdown' or 'json'`,+ );+ }+ return raw;+}++// ----- brain_feedback ------------------------------------------------------++/**+ * Build the slug used in the signal / preference filename. We never let+ * the agent decide the slug directly β taking `topic` as the slug stem+ * is what the design doc Β§9.2 prescribes (slugs are deterministic from+ * topic). The slug is run through `slugify` defensively so a slightly+ * mis-shaped topic still yields a filesystem-safe basename.+ */+function deriveSlug(topic: string): string {+ return slugify(topic);+}++async function toolBrainFeedback(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const topic = coerceStr(args, "topic", true)!;+ const signalRaw = coerceStr(args, "signal", true)!;+ if (+ signalRaw !== BRAIN_SIGNAL_SIGN.positive &&+ signalRaw !== BRAIN_SIGNAL_SIGN.negative+ ) {+ throw new MCPError(+ INVALID_PARAMS,+ `argument 'signal' must be 'positive' or 'negative'`,+ );+ }+ const principle = coerceStr(args, "principle", true)!;+ const scope = coerceStr(args, "scope", false);+ const source = coerceStrList(args, "source");+ const agentArg = coerceStr(args, "agent", false);+ const raw = coerceStr(args, "raw", false);+ const forceConfirmed = coerceBool(args, "force_confirmed");++ const agent =+ normalizeAgentArgument(agentArg) ?? resolveAgentName(ctx.configPath ?? undefined);+ const now = new Date();+ const date = isoDate(now);+ const createdAt = isoSecond(now);+ const slug = deriveSlug(topic);++ // 1. Always write the signal to inbox/. Mirrors the CLI handler so the+ // audit trail in `Brain/log/` and `inbox/processed/` stays consistent+ // across CLI and MCP entry points. `--force-confirmed` ADDITIONALLY+ // creates a confirmed pref below.+ const sigResult = writeSignal(ctx.vault, {+ topic: topic.trim(),+ signal: signalRaw as BrainSignalSign,+ agent,+ principle: principle.trim(),+ created_at: createdAt,+ date,+ slug,+ ...(scope ? { scope } : {}),+ ...(source && source.length > 0 ? { source } : {}),+ ...(raw ? { raw } : {}),+ });++ try {+ appendLogEvent(ctx.vault, {+ timestamp: createdAt,+ eventType: BRAIN_LOG_EVENT_KIND.feedback,+ body: {+ signal: `[[${sigResult.id}]]`,+ topic: topic.trim(),+ sign: signalRaw,+ agent,+ },+ });+ } catch (err) {+ process.stderr.write(+ `warning: append feedback log failed: ${(err as Error).message}\n`,+ );+ }++ let prefResult: { path: string; id: string } | null = null;+ if (forceConfirmed) {+ // Escape hatch: skip the dream pass and create the confirmed rule now.+ // `confirmed_at` is now; `unconfirmed_until` is also now so the trial+ // window collapses on inspection. The just-written signal is recorded+ // as the rule's origin under `evidenced_by`.+ prefResult = writePreference(ctx.vault, {+ slug,+ topic: topic.trim(),+ principle: principle.trim(),+ created_at: createdAt,+ unconfirmed_until: createdAt,+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ evidenced_by: [`[[${sigResult.id}]]`],+ confirmed_at: createdAt,+ ...(scope ? { scope } : {}),+ });+ try {+ // Offset by 1s so the force-confirmed event sorts after the feedback+ // event on the same UTC second (parseLogDay is stable on ties, but a+ // visible chronology reads cleaner).+ appendLogEvent(ctx.vault, {+ timestamp: isoSecond(new Date(now.getTime() + 1000)),+ eventType: BRAIN_LOG_EVENT_KIND.forceConfirmed,+ body: {+ preference: `[[${prefResult.id}]]`,+ agent,+ },+ });+ } catch (err) {+ process.stderr.write(+ `warning: append force-confirmed log failed: ${(err as Error).message}\n`,+ );+ }+ }++ return {+ kind: prefResult ? "preference" : "signal",+ signal_path: vaultRelativeSafe(ctx.vault, sigResult.path),+ signal_absolute_path: resolve(sigResult.path),+ signal_id: sigResult.id,+ ...(prefResult+ ? {+ preference_path: vaultRelativeSafe(ctx.vault, prefResult.path),+ preference_absolute_path: resolve(prefResult.path),+ preference_id: prefResult.id,+ // Back-compat: top-level `path`/`id` previously pointed at the+ // pref on the force-confirmed branch. Keep them aligned for+ // callers that look at the bare fields.+ path: vaultRelativeSafe(ctx.vault, prefResult.path),+ absolute_path: resolve(prefResult.path),+ id: prefResult.id,+ }+ : {+ path: vaultRelativeSafe(ctx.vault, sigResult.path),+ absolute_path: resolve(sigResult.path),+ id: sigResult.id,+ }),+ agent,+ };+}++// ----- brain_dream ---------------------------------------------------------++async function toolBrainDream(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const dryRun = coerceBool(args, "dry_run");+ const nowDate = coerceIsoDate(args, "now");++ const summary = dream(ctx.vault, {+ dryRun,+ ...(nowDate ? { now: nowDate } : {}),+ });++ // The summary is already a Plain Old Frozen Object β JSON-serialise+ // verbatim. We surface `snapshot_path` / `log_path` as vault-relative+ // for caller convenience while preserving the absolute path as well.+ return {+ run_id: summary.run_id,+ changed: summary.changed,+ dry_run: dryRun,+ new_unconfirmed: [...summary.new_unconfirmed],+ confirmed: [...summary.confirmed],+ retired: summary.retired.map((r) => ({ id: r.id, reason: r.reason })),+ contradictions: [...summary.contradictions],+ moved_to_processed: [...summary.moved_to_processed],+ snapshot_path: summary.snapshot_path+ ? vaultRelativeSafe(ctx.vault, summary.snapshot_path)+ : null,+ log_path: summary.log_path+ ? vaultRelativeSafe(ctx.vault, summary.log_path)+ : null,+ };+}++// ----- brain_apply_evidence ------------------------------------------------++async function toolBrainApplyEvidence(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const prefId = coerceStr(args, "pref_id", true)!;+ const artifact = coerceStr(args, "artifact", true)!;+ const resultRaw = coerceStr(args, "result", true)!;+ if (+ resultRaw !== BRAIN_APPLY_RESULT.applied &&+ resultRaw !== BRAIN_APPLY_RESULT.violated+ ) {+ throw new MCPError(+ INVALID_PARAMS,+ `argument 'result' must be 'applied' or 'violated'`,+ );+ }+ const agentArg = coerceStr(args, "agent", false);+ const note = coerceStr(args, "note", false);++ const agent =+ normalizeAgentArgument(agentArg) ?? resolveAgentName(ctx.configPath ?? undefined);++ const input: AppendApplyEvidenceInput = {+ pref_id: prefId,+ artifact,+ result: resultRaw as BrainApplyResult,+ agent,+ ...(note ? { note } : {}),+ };++ // Surface BrainPreferenceNotFoundError as a tool-level error envelope+ // (isError: true) rather than an MCP protocol error. The design doc+ // says "not an error condition" β the agent should see an informative+ // payload that explains what to do next, not a JSON-RPC error frame.+ try {+ const res = appendApplyEvidence(ctx.vault, input);+ return {+ logged_at: res.logged_at,+ log_path: vaultRelativeSafe(ctx.vault, res.log_path),+ absolute_log_path: resolve(res.log_path),+ agent,+ };+ } catch (exc) {+ if (exc instanceof BrainPreferenceNotFoundError) {+ // Re-throw as a non-MCPError so `server.handleToolsCall` packs it+ // into a `toolError` envelope (isError: true, single-text content).+ // This matches the pay-memory "pending request not found" pattern.+ throw new Error(exc.message);+ }+ throw exc;+ }+}++// ----- brain_digest --------------------------------------------------------++async function toolBrainDigest(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const since = coerceIsoDate(args, "since");+ const until = coerceIsoDate(args, "until");+ const format = coerceFormat(args) satisfies DigestFormat;++ const result = renderDigest(ctx.vault, {+ ...(since ? { since } : {}),+ ...(until ? { until } : {}),+ format,+ });++ return {+ format,+ empty: result.empty,+ content: result.content,+ };+}++// ----- brain_query ---------------------------------------------------------++async function toolBrainQuery(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const preference = coerceStr(args, "preference", false);+ const topic = coerceStr(args, "topic", false);+ const since = coerceIsoDate(args, "since");+ // `format` is accepted for forward-compat (design doc Β§9.2 names it),+ // but the structured response shape is identical regardless β the+ // caller serialises however they want. We validate the value to catch+ // typos early.+ coerceFormat(args);++ const supplied = [preference, topic, since].filter((v) => v !== null).length;+ if (supplied === 0) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_query requires exactly one of: preference, topic, since",+ );+ }+ if (supplied > 1) {+ throw new MCPError(+ INVALID_PARAMS,+ "brain_query accepts at most one of: preference, topic, since",+ );+ }++ if (preference !== null) {+ try {+ const res = queryByPreference(ctx.vault, preference);+ return {+ mode: "preference",+ preference: serializePreference(res.preference),+ evidence: res.evidence.map(serializeLogEntry),+ };+ } catch (exc) {+ if (exc instanceof BrainNotFoundError) {+ throw new Error(exc.message);+ }+ throw exc;+ }+ }++ if (topic !== null) {+ const res = queryByTopic(ctx.vault, topic);+ return {+ mode: "topic",+ topic,+ signals: res.signals.map(serializeSignal),+ preference: res.preference ? serializePreference(res.preference) : null,+ all_log_events: res.all_log_events.map(serializeLogEntry),+ };+ }++ // since+ const res = queryByLogSince(ctx.vault, since!);+ return {+ mode: "since",+ since: since!.toISOString(),+ events: res.map(serializeLogEntry),+ };+}++// ----- brain_doctor --------------------------------------------------------++async function toolBrainDoctor(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const strict = coerceBool(args, "strict");+ const format = coerceFormat(args);++ const result = runDoctor(ctx.vault, { strict });++ // Decide a single ok flag β `strict` only changes the CLI exit code,+ // so we mirror that semantic here: with `strict`, warnings demote ok+ // to false. Errors always do.+ const ok =+ result.errors.length === 0 && (!strict || result.warnings.length === 0);++ return {+ format,+ ok,+ strict,+ errors: result.errors.map((i) => ({+ severity: i.severity,+ code: i.code,+ message: i.message,+ ...(i.path !== undefined ? { path: vaultRelativeSafe(ctx.vault, i.path) } : {}),+ })),+ warnings: result.warnings.map((i) => ({+ severity: i.severity,+ code: i.code,+ message: i.message,+ ...(i.path !== undefined ? { path: vaultRelativeSafe(ctx.vault, i.path) } : {}),+ })),+ };+}++// ----- Serializers ---------------------------------------------------------++function serializeSignal(s: BrainSignal): Record<string, unknown> {+ return {+ kind: s.kind,+ id: s.id,+ created_at: s.created_at,+ topic: s.topic,+ signal: s.signal,+ agent: s.agent,+ principle: s.principle,+ tags: [...s.tags],+ ...(s.scope !== undefined ? { scope: s.scope } : {}),+ ...(s.source !== undefined ? { source: [...s.source] } : {}),+ ...(s.raw !== undefined ? { raw: s.raw } : {}),+ };+}++function serializePreference(+ p: BrainPreference | BrainRetired,+): Record<string, unknown> {+ if (p.kind === "brain-retired") {+ return {+ kind: p.kind,+ id: p.id,+ status: p.status,+ retired_at: p.retired_at,+ retired_reason: p.retired_reason,+ retired_by: p.retired_by,+ ...(p.superseded_by !== undefined ? { superseded_by: p.superseded_by } : {}),+ created_at: p.created_at,+ topic: p.topic,+ ...(p.scope !== undefined ? { scope: p.scope } : {}),+ principle: p.principle,+ evidenced_by: [...p.evidenced_by],+ applied_count: p.applied_count,+ violated_count: p.violated_count,+ last_evidence_at: p.last_evidence_at,+ confidence: p.confidence,+ pinned: p.pinned,+ tags: [...p.tags],+ ...(p.aliases !== undefined ? { aliases: [...p.aliases] } : {}),+ };+ }+ return {+ kind: p.kind,+ id: p.id,+ created_at: p.created_at,+ confirmed_at: p.confirmed_at,+ unconfirmed_until: p.unconfirmed_until,+ topic: p.topic,+ ...(p.scope !== undefined ? { scope: p.scope } : {}),+ status: p.status,+ principle: p.principle,+ evidenced_by: [...p.evidenced_by],+ applied_count: p.applied_count,+ violated_count: p.violated_count,+ last_evidence_at: p.last_evidence_at,+ confidence: p.confidence,+ pinned: p.pinned,+ tags: [...p.tags],+ ...(p.supersedes !== undefined ? { supersedes: p.supersedes } : {}),+ ...(p.aliases !== undefined ? { aliases: [...p.aliases] } : {}),+ };+}++function serializeLogEntry(e: BrainLogEntry): Record<string, unknown> {+ // Preserve the structured payload verbatim (array values stay arrays).+ // JSON.stringify handles `ReadonlyArray<string>` and string values+ // identically. `Object.entries` widens the value type to `unknown` for+ // generic-keyed records under `verbatimModuleSyntax`; narrow explicitly.+ const body: Record<string, string | ReadonlyArray<string>> = {};+ for (const [k, v] of Object.entries(e.body) as ReadonlyArray<+ readonly [string, string | ReadonlyArray<string>]+ >) {+ body[k] = Array.isArray(v) ? [...v] : v;+ }+ return {+ timestamp: e.timestamp,+ event_type: e.eventType,+ body,+ };+}++// ----- Misc ----------------------------------------------------------------++/**+ * Produce a vault-relative path, swallowing errors (Pay Memory uses the+ * same defensive pattern for output rendering). Exported for unit tests+ * β internal callers stay inside this module.+ *+ * @internal+ */+export function vaultRelativeSafe(vault: string, target: string): string {+ const absVault = resolve(vault);+ const absTarget = resolve(target);+ // Use Node's path.relative so the separator handling matches the host+ // OS (forward-slashes on POSIX, back-slashes on Windows). The prior+ // implementation hard-coded `"/"` and silently broke on Windows when+ // the vault sat under e.g. `C:\Users\...`.+ const rel = relative(absVault, absTarget);+ if (rel === "") return "";+ // `relative()` returns a path starting with `..` (or, in rare drive-+ // mismatch cases on Windows, an absolute path) when the target sits+ // outside the vault. In both situations we return the original target+ // unchanged β callers treat that as "not under vault" and render it+ // as-is.+ if (rel.startsWith("..") || isAbsolute(rel)) return target;+ return rel;+}++// Reference to satisfy "may need to look up pref path in MCP handler"+// without re-exporting the helper from `core/brain/paths.ts` for the+// public surface. Used only by the typecheck on `BrainPreferenceNotFoundError`+// rethrow; we keep the import alive intentionally so future grep finds+// the MCP layer using the same path helper as the core.+//+// (The function is invoked indirectly through `appendApplyEvidence`.)+void preferencePath;++// Loadable so future MCP-level config introspection can reuse the+// validation surface without depending on the CLI module. Currently+// unused β explicit import keeps the dependency graph documented.+void loadBrainConfig;+void existsSync;++// ----- Tool registration ---------------------------------------------------++export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([+ {+ name: "brain_feedback",+ description:+ "Record one Brain taste signal in `Brain/inbox/sig-*.md`. With `force_confirmed: true`, create the preference directly (skips the dream trial window).",+ inputSchema: {+ type: "object",+ properties: {+ topic: {+ type: "string",+ description:+ "Stable kebab-slug for the rule, e.g. `no-internal-abbrev`.",+ },+ signal: {+ type: "string",+ enum: ["positive", "negative"],+ description:+ "`positive` when the principle is the rule to follow, `negative` when it's what to avoid.",+ },+ principle: {+ type: "string",+ description:+ "One-line, agent-readable formulation of the rule (imperative voice).",+ },+ scope: {+ type: "string",+ description:+ "Optional soft category for later application-scope matching, e.g. `writing`, `coding`.",+ },+ source: {+ type: "array",+ items: { type: "string" },+ description:+ "Optional wikilinks to the artifacts or notes that triggered the signal.",+ },+ agent: {+ type: "string",+ description:+ "Optional agent identity override; defaults to the server-resolved name.",+ },+ raw: {+ type: "string",+ description:+ "Optional free-form raw quote (rendered under `## Raw` in the signal file).",+ },+ force_confirmed: {+ type: "boolean",+ description:+ "When true, additionally creates a `pref-*` resource with `status: confirmed` alongside the inbox signal. The signal is always written to `Brain/inbox/`; this flag only adds an immediately-active preference (skipping the usual dream-pass promotion step).",+ },+ },+ required: ["topic", "signal", "principle"],+ additionalProperties: false,+ },+ handler: toolBrainFeedback,+ },+ {+ name: "brain_dream",+ description:+ "Run the deterministic learning pass over `Brain/inbox/` (clusters signals, promotes preferences, retires stale rules). Typically scheduled via cron rather than invoked interactively.",+ inputSchema: {+ type: "object",+ properties: {+ dry_run: {+ type: "boolean",+ description:+ "When true, compute the plan without writing any files.",+ },+ now: {+ type: "string",+ description:+ "Optional ISO-8601 timestamp used as the wall clock for the run (testing / replay).",+ },+ },+ additionalProperties: false,+ },+ handler: toolBrainDream,+ },+ {+ name: "brain_apply_evidence",+ description:+ "Record whether an active preference was applied or violated against a freshly-produced durable artifact. Appends one event to `Brain/log/<today>.md`.",+ inputSchema: {+ type: "object",+ properties: {+ pref_id: {+ type: "string",+ description:+ "Preference id (`pref-<slug>` or bare `<slug>`).",+ },+ artifact: {+ type: "string",+ description:+ "Wikilink identifying the artifact, e.g. `[[Daily/2026.05.14#section]]` or `[[src/cli/main.ts]]`.",+ },+ result: {+ type: "string",+ enum: ["applied", "violated"],+ description:+ "`applied` if the rule held in this artifact, `violated` if it was broken.",+ },+ agent: {+ type: "string",+ description:+ "Optional agent identity override; defaults to the server-resolved name.",+ },+ note: {+ type: "string",+ description: "Optional one-line context.",+ },+ },+ required: ["pref_id", "artifact", "result"],+ additionalProperties: false,+ },+ handler: toolBrainApplyEvidence,+ },+ {+ name: "brain_digest",+ description:+ "Render a human-readable summary of Brain activity in the last 24h (default) or a custom window. Read-only.",+ inputSchema: {+ type: "object",+ properties: {+ since: {+ type: "string",+ description:+ "Inclusive lower bound (ISO-8601). Defaults to `until - 24h`.",+ },+ until: {+ type: "string",+ description:+ "Exclusive upper bound (ISO-8601). Defaults to `now`.",+ },+ format: {+ type: "string",+ enum: ["markdown", "json"],+ description: "Output format. Defaults to `markdown`.",+ },+ },+ additionalProperties: false,+ },+ handler: toolBrainDigest,+ },+ {+ name: "brain_query",+ description:+ "Read-only lookup: one preference + its evidence trail, all artifacts under a topic, or every log event after a timestamp. Exactly one of `preference`, `topic`, `since` must be supplied.",+ inputSchema: {+ type: "object",+ properties: {+ preference: {+ type: "string",+ description:+ "Preference id (`pref-...` or `ret-...`) to look up with its evidence trail.",+ },+ topic: {+ type: "string",+ description:+ "Topic slug to aggregate signals + active/retired preference + log events.",+ },+ since: {+ type: "string",+ description:+ "ISO-8601 timestamp; returns every Brain log event with timestamp >= since.",+ },+ format: {+ type: "string",+ enum: ["markdown", "json"],+ description:+ "Reserved for forward-compat; the structured response is the same regardless.",+ },+ },+ additionalProperties: false,+ },+ handler: toolBrainQuery,+ },+ {+ name: "brain_doctor",+ description:+ "Validate `Brain/` invariants: status-vs-folder consistency, frontmatter validity, duplicate ids, ISO parsing, log header parsing. Read-only.",+ inputSchema: {+ type: "object",+ properties: {+ strict: {+ type: "boolean",+ description:+ "When true, warnings demote `ok` to false (CLI exit-code parity).",+ },+ format: {+ type: "string",+ enum: ["markdown", "json"],+ description:+ "Output format hint. Structured result is identical; caller decides rendering.",+ },+ },+ additionalProperties: false,+ },+ handler: toolBrainDoctor,+ },+]);diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.tsindex dde2ec87..4400d22f 100644--- a/src/mcp/instructions.ts+++ b/src/mcp/instructions.ts@@ -1,44 +1,48 @@/*** Server-supplied instructions returned in `initialize.instructions`.*- * Mirrors `_build_instructions` from the legacy Python implementation.- * Keep the wording identical β the same string is read by Hermes, Claude- * Code, Codex, and OpenClaw, and is referenced verbatim in test fixtures.+ * In v0.9.0 the wording shifts from a single event-log-centric flow to+ * the Brain observing-memory layer. Six new `brain_*` tools are the+ * canonical writable surface; `event_log_append` and+ * `second_brain_capture` are no longer advertised to agents (their+ * handlers remain on disk for shell-side use).*/export function buildInstructions(defaultAgent: string): string {return (`You are @${defaultAgent} on this Open Second Brain vault. ` +"Always log under this identity; do not invent or change the name.\n\n" +- "When to call event_log_append:\n" +- " - immediately after producing a durable artifact, including:\n" +- " * code shipped, bug fixed, refactor merged\n" +- " * config / deployment / infrastructure change\n" +- " * instruction-file edit (CLAUDE.md, SOUL.md, plugin docs, " +- "system prompts, similar)\n" +- " * content artifact created (post, draft, documentation, " +- "marketing copy, release notes)\n" +- " * research, investigation, or analysis that produced a " +- "concrete finding, design, or decision worth recalling later\n" +- " * discovery of an external fact (CLI behaviour change, " +- "API quirk, undocumented edge case) that future sessions should " +- "know\n" +- " - skip for: pure discussion or brainstorming without " +- "conclusion, read-only queries, or planning that hasn't yet " +- "produced an artifact\n\n" +- 'If unsure, ask: "would future-me want to find this in the log ' +- 'by searching for it later?". If yes, log it.\n\n' +- "How to format the `message` argument:\n" +- " - plain prose describing what was done / found / decided and " +- "why it matters\n" +- " - DO NOT prepend `HH:MM β` or `@<name> β` to the message; " +- "the server adds these automatically\n" +- " - terse, append-only, factual; never edit historical lines\n\n" +- "Identity is resolved server-side. Do not pass the `agent` argument " +- "unless deliberately logging on another agent's behalf.\n\n" ++ "Brain tools are the agent-facing writable surface (design doc Β§9).\n" ++ " - brain_feedback β call once per taste signal the user (or a " ++ "teammate agent) expresses: corrections (\"don't do X\"), stated " ++ "preferences (\"use A instead of B\"), or process rules that " ++ "should outlast the current turn. With `force_confirmed: true` " ++ "the preference is created directly (skipping the dream trial " ++ "window).\n" ++ " - brain_apply_evidence β call right after you produce a " ++ "durable artifact (code shipped, config / instruction edited, " ++ "content drafted) and at least one preference in " ++ "`Brain/preferences/` scopes to that artifact. Record " ++ "`result: applied | violated` per (preference, artifact) pair.\n" ++ " - brain_dream β runs the deterministic learning pass " ++ "(clusters signals, promotes preferences, retires stale rules). " ++ "Usually scheduled via cron, not invoked interactively.\n" ++ " - brain_digest β read-only summary of the last activity " ++ "window. Default format is Markdown; pass `format: \"json\"` for " ++ "programmatic use.\n" ++ " - brain_query β read-only lookup by `preference`, `topic`, " ++ "or `since` (exactly one). Use this to discover applicable rules " ++ "before calling `brain_apply_evidence`.\n" ++ " - brain_doctor β invariant / schema health check. With " ++ "`strict: true`, warnings demote the `ok` flag.\n\n" ++ "Skip Brain calls for casual chat, exploration without a stated " ++ "rule, read-only inspection, and trivial edits. A misrecorded " ++ "signal is worse than a missed one β the dream pass surfaces " ++ "real patterns from repeat events, so prefer precision over " ++ "coverage.\n\n" +"Other tools: second_brain_status (config status), " +- "vault_health (verify vault), second_brain_query (look up notes), " +- "second_brain_capture (add wiki pages).\n\n" ++ "vault_health (verify vault), second_brain_query (look up legacy " ++ "AI Wiki / Daily notes β read-only).\n\n" +"Pay Memory tools record paid agent actions as inspectable Markdown:\n" +" - payment_memory_init bootstraps the layout and writes the " +"spending policy template (run once per vault).\n" +@@ -54,11 +58,9 @@ export function buildInstructions(defaultAgent: string): string {" - payment_report_generate aggregates a date's receipts into a " +"Markdown report.\n" +"These tools never execute payments β they only persist memory. " +- "After a successful paid call also append a daily event with " +- "event_log_append so the receipt is discoverable in `Daily/`. When " +- "an approval workflow is in use, the recommended sequence is: " +- "payment_policy_check β payment_request_approval β poll " ++ "When an approval workflow is in use, the recommended sequence " ++ "is: payment_policy_check β payment_request_approval β poll " +"payment_request_status β run `pay` β payment_receipt_append β " +- "asset_capture β payment_request_consume β event_log_append."+ "asset_capture β payment_request_consume.");}diff --git a/src/mcp/tools.ts b/src/mcp/tools.tsindex c775d31b..317a2560 100644--- a/src/mcp/tools.ts+++ b/src/mcp/tools.ts@@ -1,8 +1,19 @@/**- * MCP tool registry: the five tools exposed by Open Second Brain- * (`second_brain_status`, `second_brain_query`, `second_brain_capture`,- * `event_log_append`, `vault_health`). Each handler delegates to the- * core/* helpers so the contract stays identical to the CLI.+ * MCP tool registry. As of v0.9.0 the advertised surface is:+ *+ * - Core read/health tools (`second_brain_status`, `second_brain_query`,+ * `vault_health`).+ * - Brain tools (`brain_feedback`, `brain_dream`,+ * `brain_apply_evidence`, `brain_digest`, `brain_query`,+ * `brain_doctor`) β see `./brain-tools.ts`.+ * - Pay Memory tools (`payment_*`, `asset_capture`).+ *+ * `event_log_append` and `second_brain_capture` are intentionally+ * *not* registered here in v0.9.0 β Brain replaces them as the+ * agent-facing writable surface (design doc Β§11.1). Their handler+ * functions remain on disk (`toolEventLogAppend`, `toolCapture` below)+ * so the CLI / shell tooling keeps working; only the entries in the+ * exported tool array are removed.*/import { existsSync, mkdirSync, statSync } from "node:fs";@@ -16,6 +27,7 @@ import {} from "../core/config.ts";import { doctor } from "../core/doctor.ts";import { appendEvent, validateEventTime } from "../core/event-log.ts";+import { BRAIN_TOOLS } from "./brain-tools.ts";import {checkPolicy,consumePendingRequest,@@ -613,45 +625,12 @@ export function buildToolTable(): ToolDefinition[] {},handler: toolQuery,},- {- name: "second_brain_capture",- description: "Write a new Markdown note to AI Wiki/notes/ with frontmatter.",- inputSchema: {- type: "object",- properties: {- title: { type: "string", description: "Human-readable note title." },- content: { type: "string", description: "Markdown body of the note." },- tags: {- type: "array",- items: { type: "string" },- description: "Optional list of tag strings.",- },- overwrite: {- type: "boolean",- description: "Allow overwriting an existing note with the same slug.",- },- },- required: ["title", "content"],- additionalProperties: false,- },- handler: toolCapture,- },- {- name: "event_log_append",- description: "Append a single-line event to the daily Markdown event log.",- inputSchema: {- type: "object",- properties: {- message: { type: "string", description: "Single-line event message." },- agent: { type: "string", description: "Agent name (default 'agent')." },- date: { type: "string", description: "Optional event date in YYYY.MM.DD format." },- time: { type: "string", description: "Optional event time in 24-hour HH:MM format." },- },- required: ["message"],- additionalProperties: false,- },- handler: toolEventLogAppend,- },+ // `second_brain_capture` and `event_log_append` are intentionally+ // not advertised in v0.9.0+. Their handlers (`toolCapture`,+ // `toolEventLogAppend`) remain in this file for human-side shell+ // use (`o2b append-event`); only the entries in the exported tool+ // array are removed β see Β§11.1 of the v0.9.0 design doc.+ ...BRAIN_TOOLS,{name: "vault_health",description: "Run vault, config, and plugin manifest health checks.",diff --git a/tests/cli/brain.test.ts b/tests/cli/brain.test.tsnew file mode 100644index 00000000..d8c8a6af--- /dev/null+++ b/tests/cli/brain.test.ts@@ -0,0 +1,885 @@+/**+ * CLI tests for `o2b brain *` (Task 6, Step 25).+ *+ * Each verb is exercised end-to-end through `runCli`, which forks the+ * actual `bun src/cli/main.ts` binary. The fork model is shared with the+ * legacy CLI tests so the test surface stays consistent.+ *+ * Test-vault setup pattern:+ * 1. `o2b init --vault <tmp>` registers the vault in a per-test+ * machine config (isolated via OPEN_SECOND_BRAIN_CONFIG).+ * 2. `o2b brain init --vault <tmp>` creates the Brain skeleton.+ * 3. The verb under test runs against that vault.+ *+ * We assert exit codes (the Β§9.2 matrix) and the canonical stdout/stderr+ * patterns. Markdown body shapes are spot-checked but kept loose β the+ * unit tests under `tests/core/brain.*.test.ts` already lock the+ * renderers.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { runCli } from "../helpers/run-cli.ts";++let tmp: string;+let vault: string;+let config: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-cli-test-"));+ vault = join(tmp, "vault");+ config = join(tmp, "config.yaml");+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++/** Bootstrap a fresh vault with the Brain layer installed. */+async function bootstrap(): Promise<void> {+ const init = await runCli(["init", "--vault", vault, "--name", "Test"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(init.returncode).toBe(0);+ const brainInit = await runCli(["brain", "init", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(brainInit.returncode).toBe(0);+}++describe("brain --help", () => {+ test("prints the verb listing", async () => {+ const r = await runCli(["brain", "--help"]);+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("usage: o2b brain");+ expect(r.stdout).toContain("init");+ expect(r.stdout).toContain("feedback");+ expect(r.stdout).toContain("dream");+ expect(r.stdout).toContain("apply-evidence");+ expect(r.stdout).toContain("digest");+ expect(r.stdout).toContain("query");+ expect(r.stdout).toContain("reject");+ expect(r.stdout).toContain("pin");+ expect(r.stdout).toContain("unpin");+ expect(r.stdout).toContain("rollback");+ expect(r.stdout).toContain("doctor");+ });++ test("unknown verb exits 2 and lists known verbs", async () => {+ const r = await runCli(["brain", "no-such-verb"]);+ expect(r.returncode).toBe(2);+ expect(r.stderr).toContain("unknown brain verb");+ });++ test("unknown verb requesting --help falls back to generic help with exit 2", async () => {+ const r = await runCli(["brain", "no-such-verb", "--help"]);+ expect(r.returncode).toBe(2);+ // Should print the generic Brain help (lists known verbs), not a+ // bare placeholder line.+ expect(r.stdout).toContain("usage: o2b brain");+ expect(r.stdout).toContain("feedback");+ });++ test("known verb --help exits 0 with verb-specific help", async () => {+ const r = await runCli(["brain", "feedback", "--help"]);+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("brain feedback");+ });+});++describe("brain init", () => {+ test("creates Brain/ skeleton against a registered vault", async () => {+ const init = await runCli(["init", "--vault", vault, "--name", "Test"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(init.returncode).toBe(0);+ const r = await runCli(["brain", "init", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("brain initialized:");+ expect(existsSync(join(vault, "Brain", "_brain.yaml"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "_BRAIN.md"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "inbox"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "preferences"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "retired"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "log"))).toBe(true);+ });++ test("--json emits structured output", async () => {+ const init = await runCli(["init", "--vault", vault, "--name", "Test"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(init.returncode).toBe(0);+ const r = await runCli(["brain", "init", "--vault", vault, "--json"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(0);+ const payload = JSON.parse(r.stdout);+ expect(payload.ok).toBe(true);+ expect(Array.isArray(payload.created)).toBe(true);+ });++ test("missing vault config exits 1 with hint", async () => {+ // No prior `o2b init` β bootstrapBrain refuses.+ const cfg = join(tmp, "missing-config.yaml");+ const r = await runCli(["brain", "init", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: cfg },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr.toLowerCase()).toContain("o2b init");+ });+});++describe("brain feedback", () => {+ test("writes a signal file with all required fields", async () => {+ await bootstrap();+ const r = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "no-abbrev",+ "--signal",+ "negative",+ "--principle",+ "Do not use abbreviations",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("signal: ");+ expect(r.stdout).toContain("id: sig-");+ const inbox = readdirSync(join(vault, "Brain", "inbox"))+ .filter((n) => n.endsWith(".md"));+ expect(inbox.length).toBe(1);+ const body = readFileSync(join(vault, "Brain", "inbox", inbox[0]!), "utf8");+ expect(body).toContain("no-abbrev");+ expect(body).toContain("negative");+ });++ test("missing --topic exits 1 naming the flag", async () => {+ await bootstrap();+ const r = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--signal",+ "positive",+ "--principle",+ "x",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--topic");+ });++ test("bad --signal value exits 1", async () => {+ await bootstrap();+ const r = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "t",+ "--signal",+ "maybe",+ "--principle",+ "x",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--signal");+ });++ test("--force-confirmed writes a confirmed preference", async () => {+ await bootstrap();+ const r = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "shortcut",+ "--signal",+ "positive",+ "--principle",+ "Skip the trial window",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("status: confirmed");+ const pref = join(vault, "Brain", "preferences", "pref-shortcut.md");+ expect(existsSync(pref)).toBe(true);+ const body = readFileSync(pref, "utf8");+ expect(body).toContain("status: confirmed");+ });+});++describe("brain dream", () => {+ test("happy path on empty vault returns no-op", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "dream", "--vault", vault, "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ const payload = JSON.parse(r.stdout);+ expect(payload.changed).toBe(false);+ });++ test("--now must be ISO-8601", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "dream", "--vault", vault, "--now", "not-a-date"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--now");+ });++ test("--now rejects permissive partial dates like a bare year", async () => {+ // `new Date("2026")` happily returns 2026-01-01T00:00:00Z, which+ // would silently let an under-specified `--now` value through. The+ // strict ISO-8601 pattern rejects it.+ await bootstrap();+ const r = await runCli(+ ["brain", "dream", "--vault", vault, "--now", "2026"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--now");+ });++ test("--now rejects date-only strings without time/timezone", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "dream", "--vault", vault, "--now", "2026-05-15"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--now");+ });+});++describe("brain apply-evidence", () => {+ test("missing required flag exits 1 naming the flag", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "apply-evidence", "--vault", vault, "--artifact", "[[foo]]"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--pref");+ });++ test("unknown pref exits 2 (informational not-found)", async () => {+ await bootstrap();+ const r = await runCli(+ [+ "brain",+ "apply-evidence",+ "--vault",+ vault,+ "--pref",+ "pref-missing",+ "--artifact",+ "[[Daily/2026.05.14]]",+ "--result",+ "applied",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(2);+ expect(r.stderr).toContain("preference not found");+ });++ test("happy path appends to today's log", async () => {+ await bootstrap();+ // Seed a force-confirmed preference so apply-evidence has a target.+ const seed = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "fast",+ "--signal",+ "positive",+ "--principle",+ "Be fast",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(seed.returncode).toBe(0);+ const r = await runCli(+ [+ "brain",+ "apply-evidence",+ "--vault",+ vault,+ "--pref",+ "pref-fast",+ "--artifact",+ "[[Daily/2026.05.14]]",+ "--result",+ "applied",+ "--agent",+ "claude",+ "--note",+ "applied to draft",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("logged:");+ const logs = readdirSync(join(vault, "Brain", "log")).filter((n) =>+ n.endsWith(".md"),+ );+ expect(logs.length).toBe(1);+ const body = readFileSync(join(vault, "Brain", "log", logs[0]!), "utf8");+ expect(body).toContain("apply-evidence");+ expect(body).toContain("[[pref-fast]]");+ });+});++describe("brain digest", () => {+ test("empty vault β one-line default output", async () => {+ await bootstrap();+ const r = await runCli(["brain", "digest", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(0);+ expect(r.stdout.toLowerCase()).toContain("no changes");+ });++ test("--silent-if-empty exits 2 with no body", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "digest", "--vault", vault, "--silent-if-empty"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(2);+ expect(r.stdout.trim()).toBe("");+ });++ test("--json emits structured payload", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "digest", "--vault", vault, "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ const payload = JSON.parse(r.stdout);+ expect(payload.schema_version).toBe(1);+ expect(payload.summary.empty).toBe(true);+ });+});++describe("brain query", () => {+ test("requires one of --preference / --topic / --since", async () => {+ await bootstrap();+ const r = await runCli(["brain", "query", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--preference");+ });++ test("--topic on empty vault returns empty result", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "query", "--vault", vault, "--topic", "no-such-topic", "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ const payload = JSON.parse(r.stdout);+ expect(payload.signals.length).toBe(0);+ expect(payload.preference).toBeNull();+ });++ test("--preference on missing pref exits 2", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "query", "--vault", vault, "--preference", "pref-nope"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(2);+ expect(r.stderr).toContain("brain query");+ });++ test("--since requires ISO timestamp", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "query", "--vault", vault, "--since", "garbage"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--since");+ });+});++describe("brain reject", () => {+ test("moves a pref to retired/", async () => {+ await bootstrap();+ const seed = await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "obsolete",+ "--signal",+ "negative",+ "--principle",+ "Never do X",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(seed.returncode).toBe(0);+ const r = await runCli(+ [+ "brain",+ "reject",+ "--vault",+ vault,+ "--id",+ "pref-obsolete",+ "--reason",+ "user changed mind",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("retired: ret-obsolete");+ expect(existsSync(join(vault, "Brain", "preferences", "pref-obsolete.md"))).toBe(false);+ expect(existsSync(join(vault, "Brain", "retired", "ret-obsolete.md"))).toBe(true);+ });++ test("missing --id exits 1", async () => {+ await bootstrap();+ const r = await runCli(["brain", "reject", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--id");+ });++ test("unknown pref exits 2", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "reject", "--vault", vault, "--id", "pref-ghost"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(2);+ expect(r.stderr).toContain("preference not found");+ });++ test("pinned pref refuses without --yes", async () => {+ await bootstrap();+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "important",+ "--signal",+ "positive",+ "--principle",+ "Important rule",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ const pin = await runCli(+ ["brain", "pin", "--vault", vault, "--id", "pref-important"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(pin.returncode).toBe(0);++ const r = await runCli(+ ["brain", "reject", "--vault", vault, "--id", "pref-important"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(1);+ expect(r.stderr.toLowerCase()).toContain("pinned");+ expect(r.stderr).toContain("--yes");+ // Pref must still exist (rejection refused).+ expect(existsSync(join(vault, "Brain", "preferences", "pref-important.md"))).toBe(true);+ });++ test("pinned pref retires with --yes", async () => {+ await bootstrap();+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "important",+ "--signal",+ "positive",+ "--principle",+ "Important rule",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ await runCli(+ ["brain", "pin", "--vault", vault, "--id", "pref-important"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ const r = await runCli(+ [+ "brain",+ "reject",+ "--vault",+ vault,+ "--id",+ "pref-important",+ "--yes",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(existsSync(join(vault, "Brain", "retired", "ret-important.md"))).toBe(true);+ });+});++describe("brain pin / unpin", () => {+ async function seedPref(): Promise<void> {+ await bootstrap();+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "rule",+ "--signal",+ "positive",+ "--principle",+ "Keep going",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ }++ test("pin then idempotent rerun", async () => {+ await seedPref();+ const r1 = await runCli(+ ["brain", "pin", "--vault", vault, "--id", "pref-rule"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r1.returncode).toBe(0);+ expect(r1.stdout).toContain("pinned: pref-rule");+ const r2 = await runCli(+ ["brain", "pin", "--vault", vault, "--id", "pref-rule"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r2.returncode).toBe(0);+ expect(r2.stdout).toContain("already pinned");+ });++ test("unpin toggles back", async () => {+ await seedPref();+ await runCli(["brain", "pin", "--vault", vault, "--id", "pref-rule"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ const r = await runCli(+ ["brain", "unpin", "--vault", vault, "--id", "pref-rule"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("unpinned: pref-rule");+ });++ test("missing --id exits 1", async () => {+ await bootstrap();+ const r = await runCli(["brain", "pin", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr).toContain("--id");+ });+});++describe("brain rollback", () => {+ test("--list reports the snapshot directory contents", async () => {+ await bootstrap();+ // Force a snapshot by running dream after producing a state change.+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "rollback-target",+ "--signal",+ "positive",+ "--principle",+ "p",+ "--force-confirmed",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ await runCli(["brain", "dream", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ const r = await runCli(+ ["brain", "rollback", "--vault", vault, "--list", "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ const list = JSON.parse(r.stdout) as Array<{ run_id: string }>;+ // Snapshot may or may not have been written depending on whether+ // dream produced any state changes β accept either shape; the+ // crucial bit is that the command emitted a JSON array.+ expect(Array.isArray(list)).toBe(true);+ });++ test("requires a run_id when not using --list", async () => {+ await bootstrap();+ const r = await runCli(["brain", "rollback", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr.toLowerCase()).toContain("run_id");+ });++ test("unknown run_id exits 2", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "rollback", "--vault", vault, "no-such-run", "--yes"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(2);+ expect(r.stderr.toLowerCase()).toContain("snapshot not found");+ });++ test("--json without --yes fails fast (never hangs on a prompt)", async () => {+ await bootstrap();+ // Even on a fake run_id the dispatcher must refuse to prompt under+ // --json β otherwise scripted callers deadlock waiting for stdin.+ // The new non-interactive guard short-circuits before the snapshot+ // existence probe; we treat that as the contract under test.+ const r = await runCli(+ ["brain", "rollback", "--vault", vault, "any-run", "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ // Either 1 (non-interactive guard) or 2 (snapshot-not-found) is+ // acceptable as long as the call returns without hanging. The+ // crucial bit is no timeout.+ expect([1, 2]).toContain(r.returncode);+ });++ test("--yes restores byte-for-byte", async () => {+ await bootstrap();+ // 1. State A: one signal.+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "before",+ "--signal",+ "positive",+ "--principle",+ "p",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ // 2. Dream creates a snapshot.+ const dr = await runCli(+ ["brain", "dream", "--vault", vault, "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(dr.returncode).toBe(0);+ const dpayload = JSON.parse(dr.stdout) as {+ run_id: string;+ changed: boolean;+ };+ if (!dpayload.changed) {+ // No state change β no snapshot. Nothing to assert; this is a+ // dream-determinism quirk on near-empty vaults. We rely on the+ // prior --list test for the snapshot-listing contract.+ return;+ }+ // 3. Add a second signal (state B).+ await runCli(+ [+ "brain",+ "feedback",+ "--vault",+ vault,+ "--topic",+ "after",+ "--signal",+ "positive",+ "--principle",+ "p",+ "--agent",+ "claude",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(+ readdirSync(join(vault, "Brain", "inbox")).filter((n) =>+ n.endsWith(".md"),+ ).length,+ ).toBeGreaterThanOrEqual(1);+ // 4. Rollback to the snapshot.+ const r = await runCli(+ [+ "brain",+ "rollback",+ "--vault",+ vault,+ dpayload.run_id,+ "--yes",+ ],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ expect(r.stdout).toContain("restored:");+ });+});++describe("brain doctor", () => {+ test("clean vault reports clean", async () => {+ await bootstrap();+ const r = await runCli(["brain", "doctor", "--vault", vault], {+ env: { OPEN_SECOND_BRAIN_CONFIG: config },+ });+ expect(r.returncode).toBe(0);+ expect(r.stdout.toLowerCase()).toContain("clean");+ });++ test("--json emits structured output", async () => {+ await bootstrap();+ const r = await runCli(+ ["brain", "doctor", "--vault", vault, "--json"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ expect(r.returncode).toBe(0);+ const payload = JSON.parse(r.stdout);+ expect(Array.isArray(payload.warnings)).toBe(true);+ expect(Array.isArray(payload.errors)).toBe(true);+ });++ test("--strict promotes warnings to exit 2", async () => {+ await bootstrap();+ // Introduce a status-vs-folder warning: drop a `pref-` file whose+ // status doesn't match the folder.+ const corrupt = join(+ vault,+ "Brain",+ "preferences",+ "pref-broken.md",+ );+ // Use the same canonical shape as the writer so the parser surfaces+ // a status-folder mismatch (status='retired' under preferences/).+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });+ writeFileSync(+ corrupt,+ [+ "---",+ "kind: brain-preference",+ "id: pref-broken",+ "created_at: 2026-05-14T10:00:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:00:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "status: retired",+ "principle: x",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ "## Principle",+ "",+ "x",+ ].join("\n"),+ "utf8",+ );+ const r = await runCli(+ ["brain", "doctor", "--vault", vault, "--strict"],+ { env: { OPEN_SECOND_BRAIN_CONFIG: config } },+ );+ // Status-folder mismatch is a warning; --strict promotes to exit 2.+ // An invariant-error path would land at exit 1 (errors), and that+ // also satisfies the spirit of "doctor surfaced the corruption", so+ // we accept either non-zero code as a regression guard.+ expect([1, 2]).toContain(r.returncode);+ });+});++describe("brain vault resolution", () => {+ test("no vault flag and no machine config exits 1 with hint", async () => {+ const cfg = join(tmp, "non-existent-config.yaml");+ const r = await runCli(["brain", "doctor"], {+ env: { OPEN_SECOND_BRAIN_CONFIG: cfg },+ });+ expect(r.returncode).toBe(1);+ expect(r.stderr.toLowerCase()).toContain("vault");+ });+});diff --git a/tests/core/brain.apply-evidence.test.ts b/tests/core/brain.apply-evidence.test.tsnew file mode 100644index 00000000..7e9c36d6--- /dev/null+++ b/tests/core/brain.apply-evidence.test.ts@@ -0,0 +1,196 @@+import { afterEach, 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 {+ BrainPreferenceNotFoundError,+ appendApplyEvidence,+} from "../../src/core/brain/apply-evidence.ts";+import { parseLogDay } from "../../src/core/brain/log.ts";+import { brainConfigPath, logPath } from "../../src/core/brain/paths.ts";+import { writePreference } from "../../src/core/brain/preference.ts";+import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-apply-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-apply-cfg-"));+ configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+ // bootstrapBrain wrote `_brain.yaml`; existence sanity-check.+ if (!existsSync(brainConfigPath(vault))) {+ throw new Error("test setup failed: _brain.yaml not created");+ }+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function prefFixture(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `Rule for ${slug}`,+ created_at: "2026-05-14T10:42:00Z",+ unconfirmed_until: "2026-05-28T10:42:00Z",+ status: "unconfirmed",+ evidenced_by: [`[[sig-2026-05-13-${slug}]]`],+ scope: "writing",+ confirmed_at: null,+ });+}++describe("appendApplyEvidence β happy path", () => {+ test("logs one apply-evidence event with the expected fields", () => {+ prefFixture("no-internal-abbrev");++ const now = new Date("2026-05-14T14:22:00Z");+ const res = appendApplyEvidence(+ vault,+ {+ pref_id: "pref-no-internal-abbrev",+ artifact: "[[Daily/2026.05.14#section]]",+ result: "applied",+ agent: "claude",+ note: "Expanded OSB on first use.",+ },+ { now },+ );++ expect(res.logged_at).toBe("2026-05-14T14:22:00Z");+ expect(res.log_path).toBe(logPath(vault, "2026-05-14"));++ const { entries, warnings } = parseLogDay(vault, "2026-05-14");+ expect(warnings).toEqual([]);+ expect(entries).toHaveLength(1);+ const e = entries[0]!;+ expect(e.eventType).toBe("apply-evidence");+ expect(e.timestamp).toBe("2026-05-14T14:22:00Z");+ expect(e.body["preference"]).toBe("[[pref-no-internal-abbrev]]");+ expect(e.body["artifact"]).toBe("[[Daily/2026.05.14#section]]");+ expect(e.body["agent"]).toBe("claude");+ expect(e.body["result"]).toBe("applied");+ expect(e.body["note"]).toBe("Expanded OSB on first use.");+ });++ test("accepts the bare slug form (without `pref-` prefix)", () => {+ prefFixture("foo-rule");+ const res = appendApplyEvidence(+ vault,+ {+ pref_id: "foo-rule",+ artifact: "[[bar]]",+ result: "violated",+ agent: "claude",+ },+ { now: new Date("2026-05-14T10:00:00Z") },+ );+ const bytes = readFileSync(res.log_path, "utf8");+ expect(bytes).toContain("preference: [[pref-foo-rule]]");+ expect(bytes).toContain("result: violated");+ });+});++describe("appendApplyEvidence β missing preference", () => {+ test("throws BrainPreferenceNotFoundError when the pref file is absent", () => {+ expect(() =>+ appendApplyEvidence(vault, {+ pref_id: "pref-does-not-exist",+ artifact: "[[bar]]",+ result: "applied",+ agent: "claude",+ }),+ ).toThrow(BrainPreferenceNotFoundError);+ });++ test("error names the search path", () => {+ try {+ appendApplyEvidence(vault, {+ pref_id: "missing",+ artifact: "[[x]]",+ result: "applied",+ agent: "claude",+ });+ throw new Error("expected throw");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainPreferenceNotFoundError);+ const e = err as BrainPreferenceNotFoundError;+ expect(e.prefId).toBe("pref-missing");+ expect(e.searchedPath).toContain("Brain/preferences/pref-missing.md");+ }+ });+});++describe("appendApplyEvidence β log file creation on first event", () => {+ test("first event of the day creates the log file with header", () => {+ prefFixture("first-event");+ // No log file exists yet.+ expect(existsSync(logPath(vault, "2026-05-14"))).toBe(false);++ appendApplyEvidence(+ vault,+ {+ pref_id: "first-event",+ artifact: "[[x]]",+ result: "applied",+ agent: "claude",+ },+ { now: new Date("2026-05-14T07:00:00Z") },+ );++ expect(existsSync(logPath(vault, "2026-05-14"))).toBe(true);+ const bytes = readFileSync(logPath(vault, "2026-05-14"), "utf8");+ expect(bytes).toContain("kind: brain-log");+ expect(bytes).toContain("date: 2026-05-14");+ expect(bytes).toContain("# Brain log β 2026-05-14");+ expect(bytes).toContain("## 07:00:00Z β apply-evidence");+ });++ test("invalid `result` is rejected at the input layer", () => {+ prefFixture("bad-result");+ expect(() =>+ appendApplyEvidence(vault, {+ pref_id: "bad-result",+ artifact: "[[x]]",+ result: "neutral" as unknown as "applied",+ agent: "claude",+ }),+ ).toThrow(/must be 'applied' or 'violated'/);+ });++ test("missing required input fields throw naming the field", () => {+ prefFixture("missing-field");+ expect(() =>+ appendApplyEvidence(vault, {+ pref_id: "",+ artifact: "[[x]]",+ result: "applied",+ agent: "claude",+ }),+ ).toThrow(/missing field: pref_id/);+ expect(() =>+ appendApplyEvidence(vault, {+ pref_id: "missing-field",+ artifact: "",+ result: "applied",+ agent: "claude",+ }),+ ).toThrow(/missing field: artifact/);+ expect(() =>+ appendApplyEvidence(vault, {+ pref_id: "missing-field",+ artifact: "[[x]]",+ result: "applied",+ agent: "",+ }),+ ).toThrow(/missing field: agent/);+ });+});diff --git a/tests/core/brain.digest.test.ts b/tests/core/brain.digest.test.tsnew file mode 100644index 00000000..fc2fe190--- /dev/null+++ b/tests/core/brain.digest.test.ts@@ -0,0 +1,354 @@+/**+ * Tests for src/core/brain/digest.ts.+ *+ * The digest is a deterministic renderer over Brain state. We exercise+ * each section in isolation, the empty-window collapse, the markdown-vs-JSON+ * parity, the schema shape from Β§8.2, and the window-filtering edge.+ *+ * Fixtures are hand-built per test for isolation; the `bootstrap` helper+ * makes a vault root with Brain/ subdirs ready for writes.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ renderDigest,+ type DigestJson,+} from "../../src/core/brain/digest.ts";+import { appendLogEvent } from "../../src/core/brain/log.ts";+import { brainDirs } from "../../src/core/brain/paths.ts";+import {+ moveToRetired,+ writePreference,+ type WritePreferenceInput,+} from "../../src/core/brain/preference.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-digest-"));+ const dirs = brainDirs(tmp);+ for (const d of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ ]) {+ mkdirSync(d, { recursive: true });+ }+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++const SINCE = new Date("2026-05-13T20:00:00Z");+const UNTIL = new Date("2026-05-14T20:00:00Z");++function basePref(+ slug: string,+ overrides: Partial<WritePreferenceInput> = {},+): WritePreferenceInput {+ return {+ slug,+ topic: slug,+ principle: `Principle for ${slug}`,+ created_at: "2026-05-14T10:42:00Z",+ unconfirmed_until: "2026-05-28T10:42:00Z",+ status: "unconfirmed",+ evidenced_by: [`[[sig-${slug}-a]]`, `[[sig-${slug}-b]]`, `[[sig-${slug}-c]]`],+ scope: "writing",+ confirmed_at: null,+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence: "low",+ pinned: false,+ ...overrides,+ };+}++describe("empty-window", () => {+ test("collapses to a single-line Markdown notice and reports `empty: true`", () => {+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.empty).toBe(true);+ expect(res.content).toMatch(/^Brain digest β 2026-05-14: no changes\n$/);+ });++ test("JSON form sets `summary.empty: true` and emits empty arrays for all sections", () => {+ const res = renderDigest(tmp, {+ since: SINCE,+ until: UNTIL,+ format: "json",+ now: UNTIL,+ });+ expect(res.empty).toBe(true);+ const parsed = JSON.parse(res.content) as DigestJson;+ expect(parsed.schema_version).toBe(1);+ expect(parsed.window.since).toBe(SINCE.toISOString());+ expect(parsed.window.until).toBe(UNTIL.toISOString());+ expect(parsed.summary.empty).toBe(true);+ expect(parsed.summary.new_unconfirmed_count).toBe(0);+ expect(parsed.summary.confirmed_count).toBe(0);+ expect(parsed.summary.retired_count).toBe(0);+ expect(parsed.summary.confidence_shift_count).toBe(0);+ expect(parsed.summary.contradiction_count).toBe(0);+ expect(parsed.new_unconfirmed).toEqual([]);+ expect(parsed.confirmed).toEqual([]);+ expect(parsed.retired).toEqual([]);+ expect(parsed.confidence_shifts).toEqual([]);+ expect(parsed.contradictions).toEqual([]);+ });+});++describe("New (unconfirmed, in trial) section", () => {+ test("includes unconfirmed prefs created in the window with signal count and trial deadline", () => {+ writePreference(tmp, basePref("no-internal-abbrev"));+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.empty).toBe(false);+ expect(res.content).toContain("## New (unconfirmed, in trial)");+ expect(res.content).toContain(+ "[[pref-no-internal-abbrev]] β writing, 3 signals, trial ends 2026-05-28",+ );+ });++ test("omits unconfirmed prefs created outside the window", () => {+ writePreference(+ tmp,+ basePref("old", { created_at: "2026-04-01T00:00:00Z" }),+ );+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.empty).toBe(true);+ expect(res.content).not.toContain("[[pref-old]]");+ });+});++describe("Confirmed section", () => {+ test("lists confirmed prefs whose confirmed_at lands in the window", () => {+ writePreference(+ tmp,+ basePref("prefer-typed-errors", {+ status: "confirmed",+ confirmed_at: "2026-05-14T11:00:00Z",+ applied_count: 1,+ last_evidence_at: "2026-05-14T11:00:00Z",+ }),+ );+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T11:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-prefer-typed-errors]]",+ artifact: "[[Daily/2026.05.14]]",+ agent: "claude",+ result: "applied",+ },+ });+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.content).toContain("## Confirmed");+ expect(res.content).toContain(+ "[[pref-prefer-typed-errors]] β writing, first applied in [[Daily/2026.05.14]]",+ );+ });+});++describe("Retired section", () => {+ test("lists retired prefs with reason and days_stale for stale-no-evidence", () => {+ const w = writePreference(+ tmp,+ basePref("prefer-bullets-over-prose", {+ status: "confirmed",+ confirmed_at: "2026-02-12T05:00:00Z",+ created_at: "2026-02-12T05:00:00Z",+ last_evidence_at: "2026-02-12T05:00:00Z",+ }),+ );+ moveToRetired(tmp, w.path, "stale-no-evidence", {+ now: new Date("2026-05-14T05:00:00Z"),+ retired_by: "[[Brain/log/2026-05-14]]",+ });+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.content).toContain("## Retired");+ // 2026-02-12 β 2026-05-14 = 91 days.+ expect(res.content).toMatch(+ /\[\[ret-prefer-bullets-over-prose\]\] β writing, stale-no-evidence \(91 days\)/,+ );+ });++ test("non-stale reasons render without the days_stale parenthetical", () => {+ const w = writePreference(tmp, basePref("rebut-me"));+ moveToRetired(tmp, w.path, "rebutted", {+ now: new Date("2026-05-14T05:00:00Z"),+ retired_by: "[[Brain/log/2026-05-14]]",+ });+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.content).toContain("[[ret-rebut-me]] β writing, rebutted");+ expect(res.content).not.toMatch(/rebutted\s*\(\d+ days\)/);+ });+});++describe("Markdown β JSON parity", () => {+ test("a fixture with one of each section type renders consistently across formats", () => {+ // New (unconfirmed) β 'aaa' created in window.+ writePreference(tmp, basePref("aaa"));+ // Confirmed β 'bbb' confirmed in window.+ writePreference(+ tmp,+ basePref("bbb", {+ status: "confirmed",+ confirmed_at: "2026-05-14T11:00:00Z",+ applied_count: 1,+ }),+ );+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T11:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-bbb]]",+ artifact: "[[Daily/2026.05.14]]",+ agent: "claude",+ result: "applied",+ },+ });+ // Retired β 'ccc' moved within window.+ const ccc = writePreference(tmp, basePref("ccc"));+ moveToRetired(tmp, ccc.path, "rebutted", {+ now: new Date("2026-05-14T12:00:00Z"),+ retired_by: "[[Brain/log/2026-05-14]]",+ });++ const md = renderDigest(tmp, { since: SINCE, until: UNTIL });+ const j = renderDigest(tmp, {+ since: SINCE,+ until: UNTIL,+ format: "json",+ now: UNTIL,+ });+ expect(md.empty).toBe(false);+ expect(j.empty).toBe(false);+ const parsed = JSON.parse(j.content) as DigestJson;+ expect(parsed.new_unconfirmed.map((x) => x.id)).toEqual(["pref-aaa"]);+ expect(parsed.confirmed.map((x) => x.id)).toEqual(["pref-bbb"]);+ expect(parsed.retired.map((x) => x.id)).toEqual(["ret-ccc"]);+ // Markdown contains every id too.+ expect(md.content).toContain("[[pref-aaa]]");+ expect(md.content).toContain("[[pref-bbb]]");+ expect(md.content).toContain("[[ret-ccc]]");+ });+});++describe("window filtering", () => {+ test("entries timestamped before `since` are excluded", () => {+ writePreference(+ tmp,+ basePref("before-window", { created_at: "2026-04-01T00:00:00Z" }),+ );+ writePreference(tmp, basePref("inside-window"));+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.content).toContain("[[pref-inside-window]]");+ expect(res.content).not.toContain("[[pref-before-window]]");+ });++ test("the upper bound is exclusive β until timestamp itself is dropped", () => {+ // created_at = until exactly β must be excluded.+ writePreference(+ tmp,+ basePref("on-the-edge", { created_at: UNTIL.toISOString() }),+ );+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ expect(res.empty).toBe(true);+ });+});++describe("graceful degradation for confidence shifts / contradictions", () => {+ test("a dream event without payload data renders empty sections without throwing", () => {+ // A dream event with no `confidence_shifts` / `contradictions`+ // bullets β what Task 3's current iteration may emit. We require+ // the renderer to tolerate it.+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:00:00Z",+ eventType: "dream",+ body: {+ run_id: "dream-2026-05-14-100000",+ input_signals: "3",+ new_unconfirmed: ["[[pref-x]]"],+ },+ });+ const res = renderDigest(tmp, { since: SINCE, until: UNTIL });+ // Empty because no preference exists with matching window dates+ // and no shifts/contradictions in the payload.+ expect(res.empty).toBe(true);+ });++ test("a dream event with confidence_shifts populates the section", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:00:00Z",+ eventType: "dream",+ body: {+ run_id: "dream-2026-05-14-100000",+ confidence_shifts: [+ "[[pref-no-internal-abbrev]] medium -> high (applied: 11, violated: 0)",+ ],+ },+ });+ const res = renderDigest(tmp, {+ since: SINCE,+ until: UNTIL,+ format: "json",+ now: UNTIL,+ });+ const parsed = JSON.parse(res.content) as DigestJson;+ expect(parsed.confidence_shifts).toHaveLength(1);+ expect(parsed.confidence_shifts[0]!.id).toBe("pref-no-internal-abbrev");+ expect(parsed.confidence_shifts[0]!.from).toBe("medium");+ expect(parsed.confidence_shifts[0]!.to).toBe("high");+ expect(parsed.confidence_shifts[0]!.applied_count).toBe(11);+ expect(parsed.confidence_shifts[0]!.violated_count).toBe(0);+ });+});++describe("`empty` flag semantics", () => {+ test("non-empty data yields empty=false; CLI can use this to skip output", () => {+ writePreference(tmp, basePref("alpha"));+ const md = renderDigest(tmp, { since: SINCE, until: UNTIL });+ const js = renderDigest(tmp, {+ since: SINCE,+ until: UNTIL,+ format: "json",+ now: UNTIL,+ });+ expect(md.empty).toBe(false);+ expect(js.empty).toBe(false);+ });++ test("default window is the last 24 hours when `since` is omitted", () => {+ const now = new Date("2026-05-14T20:00:00Z");+ writePreference(+ tmp,+ basePref("recent", { created_at: "2026-05-14T15:00:00Z" }),+ );+ writePreference(+ tmp,+ basePref("old", { created_at: "2026-04-01T00:00:00Z" }),+ );+ const res = renderDigest(tmp, { until: now });+ expect(res.content).toContain("[[pref-recent]]");+ expect(res.content).not.toContain("[[pref-old]]");+ });+});++describe("validation", () => {+ test("rejects `since > until`", () => {+ expect(() =>+ renderDigest(tmp, {+ since: new Date("2026-05-15T00:00:00Z"),+ until: new Date("2026-05-14T00:00:00Z"),+ }),+ ).toThrow(RangeError);+ });+});diff --git a/tests/core/brain.doctor.test.ts b/tests/core/brain.doctor.test.tsnew file mode 100644index 00000000..3c9e5076--- /dev/null+++ b/tests/core/brain.doctor.test.ts@@ -0,0 +1,410 @@+/**+ * Tests for src/core/brain/doctor.ts.+ *+ * Each invariant gets its own test: status-vs-folder mismatch, broken+ * wikilink, duplicate id, invalid ISO, malformed log header, unknown+ * schema version. The clean-vault and bootstrap-only cases assert that+ * a freshly initialised Brain layer reports zero issues.+ *+ * Fixtures are built by hand (writeFileSync) when the test specifically+ * needs a malformed file; otherwise we use the canonical writers so the+ * inputs match what the real Brain operations produce.+ */++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 {+ brainConfigPath,+ brainDirs,+ logPath,+ preferencePath,+ retiredPath,+ signalPath,+} from "../../src/core/brain/paths.ts";+import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/policy.ts";+import { writePreference } from "../../src/core/brain/preference.ts";+import { writeSignal } from "../../src/core/brain/signal.ts";+import { runDoctor } from "../../src/core/brain/doctor.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-doctor-"));+ const dirs = brainDirs(tmp);+ for (const d of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ ]) {+ mkdirSync(d, { recursive: true });+ }+ // Drop a default _brain.yaml β most tests require a valid config so+ // the schema-version check passes silently.+ atomicWriteFileSync(brainConfigPath(tmp), DEFAULT_BRAIN_CONFIG_YAML);+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("clean vault", () => {+ test("brain layer with only the bootstrap config reports zero issues", () => {+ const res = runDoctor(tmp);+ expect(res.errors).toEqual([]);+ expect(res.warnings).toEqual([]);+ });++ test("a vault without Brain/ at all reports zero issues (no Brain layer present is acceptable)", () => {+ const fresh = mkdtempSync(join(tmpdir(), "o2b-doctor-no-brain-"));+ try {+ const res = runDoctor(fresh);+ expect(res.errors).toEqual([]);+ expect(res.warnings).toEqual([]);+ } finally {+ rmSync(fresh, { recursive: true, force: true });+ }+ });+});++describe("status-vs-folder mismatch", () => {+ test("a file in preferences/ with status=retired raises a status-folder-mismatch warning", () => {+ const path = preferencePath(tmp, "broken");+ writeFileSync(+ path,+ [+ "---",+ "kind: brain-preference",+ "id: pref-broken",+ "created_at: 2026-05-14T10:42:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "status: retired",+ "principle: Hand-crafted mismatch",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ "## Principle",+ "Mismatch",+ "",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(res.errors).toEqual([]);+ expect(res.warnings.some((w) => w.code === "status-folder-mismatch")).toBe(+ true,+ );+ });+});++describe("broken wikilinks", () => {+ test("a preference whose evidenced_by points at a missing signal raises a broken-wikilink warning", () => {+ writePreference(tmp, {+ slug: "alpha",+ topic: "alpha",+ principle: "rule",+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed",+ evidenced_by: ["[[sig-never-existed]]"],+ });+ const res = runDoctor(tmp);+ expect(res.errors).toEqual([]);+ expect(+ res.warnings.some(+ (w) =>+ w.code === "broken-wikilink" &&+ w.message.includes("sig-never-existed"),+ ),+ ).toBe(true);+ });++ test("a preference with an existing wikilink target produces no broken-wikilink warning", () => {+ // Create a signal first so the wikilink target resolves.+ writeSignal(tmp, {+ topic: "alpha",+ signal: "negative",+ agent: "claude",+ principle: "rule",+ created_at: "2026-05-13T10:00:00Z",+ date: "2026-05-13",+ slug: "alpha",+ });+ writePreference(tmp, {+ slug: "alpha",+ topic: "alpha",+ principle: "rule",+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed",+ evidenced_by: ["[[sig-2026-05-13-alpha]]"],+ });+ const res = runDoctor(tmp);+ expect(res.warnings.filter((w) => w.code === "broken-wikilink")).toEqual(+ [],+ );+ });+});++describe("duplicate id", () => {+ test("two preference files sharing the same id raise a duplicate-id error", () => {+ // Write the canonical pref-alpha, then drop a second file with a+ // different filename basename but the same `id` in frontmatter.+ writePreference(tmp, {+ slug: "alpha",+ topic: "alpha",+ principle: "rule",+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed",+ evidenced_by: [],+ });+ const dirs = brainDirs(tmp);+ const dupPath = join(dirs.preferences, "pref-dup-name.md");+ writeFileSync(+ dupPath,+ [+ "---",+ "kind: brain-preference",+ "id: pref-alpha", // intentional duplicate+ "created_at: 2026-05-14T10:00:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:00:00Z",+ "tags: [brain, brain/preference]",+ "topic: alpha",+ "status: unconfirmed",+ "principle: Duplicate id",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(res.errors.some((e) => e.code === "duplicate-id")).toBe(true);+ });+});++describe("invalid ISO", () => {+ test("a preference with a malformed unconfirmed_until raises an iso-invalid error", () => {+ const path = preferencePath(tmp, "bad-iso");+ writeFileSync(+ path,+ [+ "---",+ "kind: brain-preference",+ "id: pref-bad-iso",+ "created_at: 2026-05-14T10:42:00Z",+ "confirmed_at: null",+ "unconfirmed_until: not-a-real-iso",+ "tags: [brain, brain/preference]",+ "topic: bad-iso",+ "status: unconfirmed",+ "principle: Hand-crafted",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(res.errors.some((e) => e.code === "iso-invalid")).toBe(true);+ });+});++describe("malformed log header", () => {+ test("a log file with a bogus event header surfaces a log-malformed warning", () => {+ const path = logPath(tmp, "2026-05-14");+ writeFileSync(+ path,+ [+ "---",+ "kind: brain-log",+ "date: 2026-05-14",+ "tags: [brain, brain/log]",+ "---",+ "",+ "# Brain log β 2026-05-14",+ "",+ "## 10:42:00Z β dream",+ "- run_id: dream-2026-05-14-104200",+ "",+ "## NOT A VALID HEADER", // missing time / em-dash+ "- something: weird",+ "",+ "## 11:00:00Z β totally-bogus-kind", // unknown event+ "- foo: bar",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(res.warnings.some((w) => w.code === "log-malformed")).toBe(true);+ });+});++describe("schema_version", () => {+ test("unknown schema_version raises a schema-version-unknown or config-invalid error", () => {+ atomicWriteFileSync(+ brainConfigPath(tmp),+ [+ "schema_version: 999",+ "",+ "dream:",+ " candidate_threshold: 3",+ " unconfirmed_window_days: 14",+ " contradiction_window_days: 14",+ "",+ "retire:",+ " stale_evidence_days: 90",+ "",+ "confidence:",+ " low_max_applied: 2",+ " high_min_applied: 10",+ " high_freshness_factor: 0.8",+ "",+ "snapshots:",+ " retention_count: 10",+ "",+ ].join("\n"),+ );+ const res = runDoctor(tmp);+ expect(+ res.errors.some(+ (e) =>+ e.code === "schema-version-unknown" || e.code === "config-invalid",+ ),+ ).toBe(true);+ });+});++describe("required fields per kind", () => {+ test("a signal missing a required field is surfaced as an error", () => {+ const dirs = brainDirs(tmp);+ const sigPath = signalPath(tmp, "2026-05-14", "missing-fields");+ void dirs;+ writeFileSync(+ sigPath,+ [+ "---",+ "kind: brain-signal",+ "id: sig-2026-05-14-missing-fields",+ "created_at: 2026-05-14T10:00:00Z",+ "tags: [brain, brain/signal]",+ // topic missing intentionally+ "signal: negative",+ "agent: claude",+ "principle: rule",+ "---",+ "",+ "## Raw",+ "",+ "_(not provided)_",+ "",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(+ res.errors.some(+ (e) => e.code === "signal-invalid" && /topic/.test(e.message),+ ),+ ).toBe(true);+ });+});++describe("retired entries", () => {+ test("a valid retired file linking to its retired_by log produces no warnings", () => {+ // Create the log file the retired entry will link to.+ const dirs = brainDirs(tmp);+ writeFileSync(+ logPath(tmp, "2026-08-12"),+ [+ "---",+ "kind: brain-log",+ "date: 2026-08-12",+ "tags: [brain, brain/log]",+ "---",+ "",+ "# Brain log β 2026-08-12",+ "",+ "## 05:00:00Z β retire",+ "- preference: [[pref-alpha]]",+ "- reason: stale-no-evidence",+ "",+ ].join("\n"),+ "utf8",+ );+ void dirs;+ writeFileSync(+ retiredPath(tmp, "alpha"),+ [+ "---",+ "kind: brain-retired",+ "id: ret-alpha",+ "status: retired",+ "retired_at: 2026-08-12T05:00:00Z",+ "retired_reason: stale-no-evidence",+ 'retired_by: "[[2026-08-12]]"',+ "created_at: 2026-05-14T10:00:00Z",+ "tags: [brain, brain/retired]",+ "topic: alpha",+ "principle: rule",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ "## Retired",+ "Reason: stale-no-evidence",+ "",+ ].join("\n"),+ "utf8",+ );+ const res = runDoctor(tmp);+ expect(res.errors).toEqual([]);+ expect(res.warnings.filter((w) => w.code === "broken-wikilink")).toEqual(+ [],+ );+ });+});++describe("missing config", () => {+ test("absent _brain.yaml triggers a config-missing error", () => {+ // Remove the config that beforeEach() wrote.+ rmSync(brainConfigPath(tmp));+ const res = runDoctor(tmp);+ expect(res.errors.some((e) => e.code === "config-missing")).toBe(true);+ });+});diff --git a/tests/core/brain.dream.test.ts b/tests/core/brain.dream.test.tsnew file mode 100644index 00000000..ffa87973--- /dev/null+++ b/tests/core/brain.dream.test.ts@@ -0,0 +1,535 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { appendApplyEvidence } from "../../src/core/brain/apply-evidence.ts";+import { dream } from "../../src/core/brain/dream.ts";+import { parseLogDay } from "../../src/core/brain/log.ts";+import {+ brainConfigPath,+ brainDirs,+ preferencePath,+ retiredPath,+} from "../../src/core/brain/paths.ts";+import {+ moveToRetired,+ parsePreference,+ parseRetired,+ writePreference,+} from "../../src/core/brain/preference.ts";+import { writeSignal } from "../../src/core/brain/signal.ts";+import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-dream-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-dream-cfg-"));+ 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 });+});++function seedSignal(opts: {+ topic: string;+ slug: string;+ signal: "positive" | "negative";+ date: string;+ principle?: string;+}): void {+ writeSignal(vault, {+ topic: opts.topic,+ signal: opts.signal,+ agent: "claude",+ principle: opts.principle ?? `Rule for ${opts.topic}`,+ created_at: `${opts.date}T10:00:00Z`,+ date: opts.date,+ slug: opts.slug,+ scope: "writing",+ });+}++function listInboxActive(): string[] {+ const dirs = brainDirs(vault);+ return readdirSync(dirs.inbox).filter((n) => n.endsWith(".md"));+}++function listInboxProcessed(): string[] {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.processed)) return [];+ return readdirSync(dirs.processed).filter((n) => n.endsWith(".md"));+}++function listPreferences(): string[] {+ return readdirSync(brainDirs(vault).preferences).filter((n) => n.endsWith(".md"));+}++function listRetired(): string[] {+ const dirs = brainDirs(vault);+ if (!existsSync(dirs.retired)) return [];+ return readdirSync(dirs.retired).filter((n) => n.endsWith(".md"));+}++// ----- Happy path threshold ----------------------------------------------++describe("dream β happy-path threshold (3 same-sign signals)", () => {+ test("creates one unconfirmed preference and moves the signals to processed/", () => {+ seedSignal({ topic: "no-abbrev", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "no-abbrev", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "no-abbrev", slug: "c", signal: "negative", date: "2026-05-14" });+ expect(listInboxActive()).toHaveLength(3);++ const res = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ expect(res.changed).toBe(true);+ expect(res.new_unconfirmed).toEqual(["pref-no-abbrev"]);++ expect(listPreferences()).toEqual(["pref-no-abbrev.md"]);+ expect(listInboxActive()).toEqual([]);+ expect(listInboxProcessed()).toHaveLength(3);++ const pref = parsePreference(preferencePath(vault, "no-abbrev"));+ expect(pref.status).toBe("unconfirmed");+ expect(pref.applied_count).toBe(0);+ expect(pref.violated_count).toBe(0);+ expect(pref.confidence).toBe("low");+ expect(pref.evidenced_by.length).toBe(3);+ });+});++// ----- Contradiction window ------------------------------------------------++describe("dream β mixed-sign within window does not create a preference", () => {+ test("2 negative + 1 positive cancel below threshold; no pref created", () => {+ seedSignal({ topic: "mixed", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "mixed", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "mixed", slug: "c", signal: "positive", date: "2026-05-14" });++ const res = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ // Some bookkeeping still happens (contradiction flag), so we don't+ // assert `changed: false` strictly β but a pref must not appear.+ expect(listPreferences()).toEqual([]);+ expect(res.new_unconfirmed).toEqual([]);+ expect(res.contradictions).toContain("mixed");+ });+});++// ----- Rebuttal ------------------------------------------------------------++describe("dream β rebuttal of a confirmed preference", () => {+ test("3 opposite-sign signals retire the confirmed pref with reason: rebutted", () => {+ // Seed an existing confirmed pref with sign-derivation indirectly:+ // we put 3 positive signals so the "active sign" heuristic in dream+ // detects positive, and a single negative will count against it.+ // To simplify, we'll instead seed 3 negative signals to attack a+ // positive preference. We construct the pref by hand.+ writePreference(vault, {+ slug: "positive-rule",+ topic: "positive-rule",+ principle: "Do X (positive rule)",+ created_at: "2026-04-01T00:00:00Z",+ unconfirmed_until: "2026-04-15T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ confirmed_at: "2026-04-05T00:00:00Z",+ applied_count: 3,+ violated_count: 0,+ last_evidence_at: "2026-05-10T00:00:00Z",+ confidence: "medium",+ });+ // 3 opposite-sign signals.+ seedSignal({ topic: "positive-rule", slug: "r1", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "positive-rule", slug: "r2", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "positive-rule", slug: "r3", signal: "negative", date: "2026-05-14" });++ const res = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });++ // The pref should have been retired with reason rebutted.+ expect(listPreferences().some((n) => n === "pref-positive-rule.md")).toBe(false);+ expect(listRetired().some((n) => n === "ret-positive-rule.md")).toBe(true);+ const retired = parseRetired(retiredPath(vault, "positive-rule"));+ expect(retired.retired_reason).toBe("rebutted");+ expect(res.retired.map((r) => r.reason)).toContain("rebutted");+ });+});++// ----- Pin protection: stale-no-evidence ----------------------------------++describe("dream β pinned preference survives stale-no-evidence", () => {+ test("clock past stale_evidence_days does NOT retire a pinned pref", () => {+ writePreference(vault, {+ slug: "pinned-stale",+ topic: "pinned-stale",+ principle: "Pinned rule",+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-15T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ confirmed_at: "2026-01-05T00:00:00Z",+ applied_count: 5,+ violated_count: 0,+ last_evidence_at: "2026-01-10T00:00:00Z",+ confidence: "medium",+ pinned: true,+ });++ // Default stale_evidence_days = 90; pick a now well past that.+ const res = dream(vault, { now: new Date("2026-08-01T00:00:00Z") });+ expect(listPreferences()).toContain("pref-pinned-stale.md");+ expect(listRetired()).not.toContain("ret-pinned-stale.md");+ expect(res.retired.map((r) => r.id)).not.toContain("ret-pinned-stale");++ // A `retire` event with `blocked: pinned` must have been logged.+ const { entries } = parseLogDay(vault, "2026-08-01");+ const retainEvents = entries.filter(+ (e) =>+ e.eventType === "retire" &&+ typeof e.body["blocked"] === "string" &&+ e.body["blocked"] === "pinned",+ );+ expect(retainEvents.length).toBeGreaterThan(0);+ });+});++// ----- Stale-no-evidence (unpinned) ---------------------------------------++describe("dream β stale-no-evidence retires confirmed pref", () => {+ test("confirmed pref with old last_evidence_at retires", () => {+ writePreference(vault, {+ slug: "stale-rule",+ topic: "stale-rule",+ principle: "Old rule",+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-15T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ confirmed_at: "2026-01-05T00:00:00Z",+ applied_count: 3,+ violated_count: 0,+ last_evidence_at: "2026-01-10T00:00:00Z",+ confidence: "medium",+ });+ const res = dream(vault, { now: new Date("2026-08-01T00:00:00Z") });+ expect(listPreferences()).not.toContain("pref-stale-rule.md");+ expect(listRetired()).toContain("ret-stale-rule.md");+ expect(res.retired.map((r) => r.reason)).toContain("stale-no-evidence");+ });++ test("superseding a retired topic uses a fresh slug so later retire does not collide", () => {+ writePreference(vault, {+ slug: "evolving-rule",+ topic: "evolving-rule",+ principle: "Old rule",+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-01-15T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ confirmed_at: "2026-01-05T00:00:00Z",+ applied_count: 3,+ violated_count: 0,+ last_evidence_at: "2026-01-10T00:00:00Z",+ confidence: "medium",+ });+ moveToRetired(vault, preferencePath(vault, "evolving-rule"), "rebutted", {+ now: new Date("2026-02-01T00:00:00Z"),+ retired_by: "[[Brain/log/2026-02-01]]",+ });++ seedSignal({ topic: "evolving-rule", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "evolving-rule", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "evolving-rule", slug: "c", signal: "negative", date: "2026-05-14" });++ const created = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ expect(created.new_unconfirmed).toEqual(["pref-evolving-rule-2"]);+ expect(listPreferences()).toContain("pref-evolving-rule-2.md");+ expect(listRetired()).toContain("ret-evolving-rule.md");++ const retired = dream(vault, { now: new Date("2026-06-15T00:00:00Z") });+ expect(retired.retired).toContainEqual({+ id: "ret-evolving-rule-2",+ reason: "expired-unconfirmed",+ });+ expect(listPreferences()).not.toContain("pref-evolving-rule-2.md");+ expect(listRetired()).toEqual(+ expect.arrayContaining(["ret-evolving-rule.md", "ret-evolving-rule-2.md"]),+ );+ });+});++// ----- Expired-unconfirmed --------------------------------------------------++describe("dream β expired-unconfirmed retires unconfirmed pref past window", () => {+ test("now > unconfirmed_until triggers retire", () => {+ writePreference(vault, {+ slug: "expiring",+ topic: "expiring",+ principle: "Trial rule",+ created_at: "2026-05-01T00:00:00Z",+ unconfirmed_until: "2026-05-10T00:00:00Z",+ status: "unconfirmed",+ evidenced_by: [],+ });+ const res = dream(vault, { now: new Date("2026-05-14T00:00:00Z") });+ expect(listPreferences()).not.toContain("pref-expiring.md");+ expect(listRetired()).toContain("ret-expiring.md");+ const retired = parseRetired(retiredPath(vault, "expiring"));+ expect(retired.retired_reason).toBe("expired-unconfirmed");+ expect(res.retired.map((r) => r.reason)).toContain("expired-unconfirmed");+ });+});++// ----- Promotion ----------------------------------------------------------++describe("dream β unconfirmed β confirmed promotion on first applied evidence", () => {+ test("first applied apply-evidence flips status and stamps confirmed_at", () => {+ writePreference(vault, {+ slug: "promote-me",+ topic: "promote-me",+ principle: "Trial rule",+ created_at: "2026-05-01T00:00:00Z",+ unconfirmed_until: "2026-05-30T00:00:00Z",+ status: "unconfirmed",+ evidenced_by: [],+ });+ // Drop an apply-evidence log entry.+ appendApplyEvidence(+ vault,+ {+ pref_id: "promote-me",+ artifact: "[[x]]",+ result: "applied",+ agent: "claude",+ },+ { now: new Date("2026-05-05T10:00:00Z") },+ );++ const res = dream(vault, { now: new Date("2026-05-06T00:00:00Z") });+ expect(res.confirmed).toContain("pref-promote-me");++ const pref = parsePreference(preferencePath(vault, "promote-me"));+ expect(pref.status).toBe("confirmed");+ expect(pref.confirmed_at).toBe("2026-05-05T10:00:00Z");+ expect(pref.applied_count).toBe(1);+ expect(pref.violated_count).toBe(0);+ expect(pref.last_evidence_at).toBe("2026-05-05T10:00:00Z");+ });+});++// ----- Confidence formula -------------------------------------------------++describe("dream β confidence formula at boundaries", () => {+ // We exercise the formula indirectly: seed evidence, run dream, read+ // pref.confidence. Default config (from policy.ts):+ // low_max_applied: 2, high_min_applied: 10+ // stale_evidence_days: 90, high_freshness_factor: 0.8+ // β "fresh" means last_evidence_at < 72 days ago.+ function setupForConfidence(slug: string, applied: number, violated: number, fresh: boolean): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: "rule",+ created_at: "2026-01-01T00:00:00Z",+ unconfirmed_until: "2026-12-31T00:00:00Z",+ status: "unconfirmed",+ evidenced_by: [],+ });+ // Generate apply-evidence entries spread over days. The most+ // recent one drives `last_evidence_at`.+ const baseDate = fresh ? "2026-05-01" : "2026-01-01";+ for (let i = 0; i < applied; i++) {+ const d = new Date(`${baseDate}T10:00:0${i % 10}Z`);+ appendApplyEvidence(+ vault,+ { pref_id: slug, artifact: `[[a${i}]]`, result: "applied", agent: "claude" },+ { now: d },+ );+ }+ for (let i = 0; i < violated; i++) {+ const d = new Date(`${baseDate}T11:00:0${i % 10}Z`);+ appendApplyEvidence(+ vault,+ { pref_id: slug, artifact: `[[v${i}]]`, result: "violated", agent: "claude" },+ { now: d },+ );+ }+ }++ test("applied=0 β low", () => {+ setupForConfidence("c-zero", 0, 0, true);+ dream(vault, { now: new Date("2026-05-15T00:00:00Z") });+ // No evidence at all means no refresh; the original `low` default+ // remains.+ const p = parsePreference(preferencePath(vault, "c-zero"));+ expect(p.confidence).toBe("low");+ });++ test("applied=2 (== low_max_applied) β low", () => {+ setupForConfidence("c-low-boundary", 2, 0, true);+ dream(vault, { now: new Date("2026-05-15T00:00:00Z") });+ const p = parsePreference(preferencePath(vault, "c-low-boundary"));+ expect(p.confidence).toBe("low");+ });++ test("applied=3, violated=0, fresh β medium", () => {+ setupForConfidence("c-medium", 3, 0, true);+ dream(vault, { now: new Date("2026-05-15T00:00:00Z") });+ const p = parsePreference(preferencePath(vault, "c-medium"));+ expect(p.confidence).toBe("medium");+ });++ test("applied=10, violated=0, fresh β high", () => {+ setupForConfidence("c-high", 10, 0, true);+ dream(vault, { now: new Date("2026-05-15T00:00:00Z") });+ const p = parsePreference(preferencePath(vault, "c-high"));+ expect(p.confidence).toBe("high");+ });++ test("applied=10, violated>=applied β low", () => {+ setupForConfidence("c-violated", 10, 10, true);+ dream(vault, { now: new Date("2026-05-15T00:00:00Z") });+ const p = parsePreference(preferencePath(vault, "c-violated"));+ expect(p.confidence).toBe("low");+ });++ test("applied=10, violated=0, stale β medium (not high β freshness fails)", () => {+ setupForConfidence("c-stale", 10, 0, false);+ // now is well beyond freshness boundary (72 days from 2026-01-01)+ // but BEFORE the stale_evidence_days retire boundary (90 days).+ // 2026-04-01 = 90 days after 2026-01-01, so we use 2026-03-20.+ dream(vault, { now: new Date("2026-03-20T00:00:00Z") });+ const p = parsePreference(preferencePath(vault, "c-stale"));+ expect(p.confidence).toBe("medium");+ });+});++// ----- Idempotency -------------------------------------------------------++describe("dream β idempotency and determinism", () => {+ test("two consecutive runs with no new input: second run returns changed=false and writes no log entry", () => {+ seedSignal({ topic: "idem", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "idem", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "idem", slug: "c", signal: "negative", date: "2026-05-14" });++ const first = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ expect(first.changed).toBe(true);++ const logBefore = readFileSync(+ join(brainDirs(vault).log, "2026-05-14.md"),+ "utf8",+ );++ // Second run on a fresh `now` so the run_id would be different.+ const second = dream(vault, { now: new Date("2026-05-14T20:01:00Z") });+ expect(second.changed).toBe(false);++ const logAfter = readFileSync(+ join(brainDirs(vault).log, "2026-05-14.md"),+ "utf8",+ );+ expect(logAfter).toBe(logBefore);+ });++ test("determinism: same vault state + same --now β byte-identical preference files", () => {+ seedSignal({ topic: "det", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "det", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "det", slug: "c", signal: "negative", date: "2026-05-14" });++ const now = new Date("2026-05-14T20:00:00Z");+ dream(vault, { now });+ const prefBytes1 = readFileSync(preferencePath(vault, "det"), "utf8");++ // Run dream again at the same now; since nothing else changed and+ // the pref already exists, the second run should be a no-op and+ // the bytes must match exactly.+ dream(vault, { now });+ const prefBytes2 = readFileSync(preferencePath(vault, "det"), "utf8");+ expect(prefBytes2).toBe(prefBytes1);+ });+});++// ----- Corrupted frontmatter tolerance ------------------------------------++describe("dream β corrupted frontmatter tolerance", () => {+ test("valid signals processed; corrupted file produces skip-corrupted-frontmatter and does NOT abort", () => {+ const dirs = brainDirs(vault);+ seedSignal({ topic: "okay", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "okay", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "okay", slug: "c", signal: "negative", date: "2026-05-14" });+ // Plant a corrupt signal file.+ writeFileSync(+ join(dirs.inbox, "sig-2026-05-14-broken.md"),+ "---\nbroken: yaml\nno-required-fields: true\n---\n\nbody\n",+ );++ const res = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ expect(res.changed).toBe(true);+ // The valid topic still got its preference.+ expect(listPreferences()).toContain("pref-okay.md");++ const { entries } = parseLogDay(vault, "2026-05-14");+ const skips = entries.filter((e) => e.eventType === "skip-corrupted-frontmatter");+ expect(skips.length).toBeGreaterThan(0);+ expect(String(skips[0]!.body["path"])).toContain("sig-2026-05-14-broken.md");+ });+});++// ----- Dry run ------------------------------------------------------------++describe("dream β dryRun mode", () => {+ test("dryRun=true: summary planned but no files mutated", () => {+ seedSignal({ topic: "dry", slug: "a", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "dry", slug: "b", signal: "negative", date: "2026-05-14" });+ seedSignal({ topic: "dry", slug: "c", signal: "negative", date: "2026-05-14" });++ const beforeInbox = listInboxActive().sort();+ const beforePrefs = listPreferences().sort();+ const beforeLog = existsSync(+ join(brainDirs(vault).log, "2026-05-14.md"),+ );++ const res = dream(vault, {+ now: new Date("2026-05-14T20:00:00Z"),+ dryRun: true,+ });+ expect(res.changed).toBe(true);+ expect(res.new_unconfirmed).toEqual(["pref-dry"]);+ expect(res.moved_to_processed).toHaveLength(3);+ // dry_run flag distinguishes a planned-only return from a real run.+ expect(res.dry_run).toBe(true);+ // No log path on dry-run: the run never wrote to log/.+ expect(res.log_path).toBeUndefined();++ // Nothing actually changed on disk.+ expect(listInboxActive().sort()).toEqual(beforeInbox);+ expect(listPreferences().sort()).toEqual(beforePrefs);+ expect(existsSync(join(brainDirs(vault).log, "2026-05-14.md"))).toBe(beforeLog);+ });+});++// ----- Empty vault edge case ---------------------------------------------++describe("dream β empty Brain (no signals, no prefs)", () => {+ test("returns changed=false with no log entry and no snapshot", () => {+ const res = dream(vault, { now: new Date("2026-05-14T20:00:00Z") });+ expect(res.changed).toBe(false);+ expect(res.snapshot_path).toBeUndefined();+ expect(existsSync(join(brainDirs(vault).log, "2026-05-14.md"))).toBe(false);+ // Brain config still in place from bootstrap.+ expect(existsSync(brainConfigPath(vault))).toBe(true);+ });+});diff --git a/tests/core/brain.init.test.ts b/tests/core/brain.init.test.tsnew file mode 100644index 00000000..5645f232--- /dev/null+++ b/tests/core/brain.init.test.ts@@ -0,0 +1,206 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ statSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { brainDirs } from "../../src/core/brain/paths.ts";+import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/policy.ts";++// Shared temp scratch for both vault and machine-config directories.+// Tests that need to assert the "missing machine config" path can+// override `configPath` explicitly to point at a non-existent file.++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-brain-init-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-brain-init-cfg-"));+ configPath = join(configHome, "config.yaml");+ // A minimal but valid plugin config: just the vault pointer. This+ // mirrors what `o2b init` writes during normal onboarding.+ mkdirSync(configHome, { recursive: true });+ writeFileSync(configPath, `vault: "${vault}"\n`, "utf8");+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++describe("bootstrapBrain β empty vault", () => {+ test("creates every Brain directory and the three managed files", () => {+ const result = bootstrapBrain(vault, { configPath });++ // Directories: every entry in brainDirs() must exist as a real dir.+ const dirs = brainDirs(vault);+ for (const dir of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ dirs.snapshots,+ ]) {+ expect(existsSync(dir)).toBe(true);+ expect(statSync(dir).isDirectory()).toBe(true);+ }++ // Files: _brain.yaml, _BRAIN.md, AI Wiki/_OPEN_SECOND_BRAIN.md.+ expect(existsSync(join(vault, "Brain", "_brain.yaml"))).toBe(true);+ expect(existsSync(join(vault, "Brain", "_BRAIN.md"))).toBe(true);+ expect(existsSync(join(vault, "AI Wiki", "_OPEN_SECOND_BRAIN.md"))).toBe(+ true,+ );++ // Counts: three created, none overwritten, none skipped.+ expect(result.created.length).toBe(3);+ expect(result.overwritten.length).toBe(0);+ expect(result.skipped.length).toBe(0);++ // _brain.yaml byte-equals the default constant.+ expect(readFileSync(join(vault, "Brain", "_brain.yaml"), "utf8")).toBe(+ DEFAULT_BRAIN_CONFIG_YAML,+ );++ // _BRAIN.md carries a recognisable headline so the test catches a+ // wrong-template / no-substitution regression cheaply.+ const manual = readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8");+ expect(manual).toContain("# Brain β operating manual");++ // Legacy overview carries the Brain-first heading and mentions the+ // two writable surfaces.+ const overview = readFileSync(+ join(vault, "AI Wiki", "_OPEN_SECOND_BRAIN.md"),+ "utf8",+ );+ expect(overview).toContain("Open Second Brain");+ expect(overview).toContain("Brain/");+ });+});++describe("bootstrapBrain β idempotent rerun", () => {+ test("second invocation without force skips Brain/ files and overwrites the legacy overview", () => {+ // First run sets the baseline.+ bootstrapBrain(vault, { configPath });++ // Mutate _brain.yaml and _BRAIN.md to detect any accidental+ // overwrite on the second pass.+ writeFileSync(join(vault, "Brain", "_brain.yaml"), "user: edited\n", "utf8");+ writeFileSync(join(vault, "Brain", "_BRAIN.md"), "user manual edits\n", "utf8");++ const second = bootstrapBrain(vault, { configPath });++ // Brain-side: both files skipped, content intact.+ expect(second.skipped).toContain(join("Brain", "_brain.yaml"));+ expect(second.skipped).toContain(join("Brain", "_BRAIN.md"));+ expect(readFileSync(join(vault, "Brain", "_brain.yaml"), "utf8")).toBe(+ "user: edited\n",+ );+ expect(readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8")).toBe(+ "user manual edits\n",+ );++ // Legacy overview is ALWAYS overwritten by design (zero-active-users+ // trade-off; see Β§12.1 of the design doc and the init.ts comment).+ expect(second.overwritten).toContain(+ join("AI Wiki", "_OPEN_SECOND_BRAIN.md"),+ );+ const overview = readFileSync(+ join(vault, "AI Wiki", "_OPEN_SECOND_BRAIN.md"),+ "utf8",+ );+ expect(overview).toContain("Open Second Brain");++ // Nothing newly created on the second run.+ expect(second.created.length).toBe(0);+ });++ test("directories are recreated idempotently with no error", () => {+ bootstrapBrain(vault, { configPath });+ // Second pass must not throw even though every directory exists.+ expect(() => bootstrapBrain(vault, { configPath })).not.toThrow();+ });+});++describe("bootstrapBrain β force overwrite", () => {+ test("force: true rewrites all three managed files", () => {+ bootstrapBrain(vault, { configPath });++ // Stomp on the canonical content so we can detect the rewrite.+ writeFileSync(join(vault, "Brain", "_brain.yaml"), "stale\n", "utf8");+ writeFileSync(join(vault, "Brain", "_BRAIN.md"), "stale\n", "utf8");+ writeFileSync(+ join(vault, "AI Wiki", "_OPEN_SECOND_BRAIN.md"),+ "stale\n",+ "utf8",+ );++ const result = bootstrapBrain(vault, { configPath, force: true });++ expect(result.overwritten).toContain(join("Brain", "_brain.yaml"));+ expect(result.overwritten).toContain(join("Brain", "_BRAIN.md"));+ expect(result.overwritten).toContain(+ join("AI Wiki", "_OPEN_SECOND_BRAIN.md"),+ );+ expect(result.skipped.length).toBe(0);++ expect(readFileSync(join(vault, "Brain", "_brain.yaml"), "utf8")).toBe(+ DEFAULT_BRAIN_CONFIG_YAML,+ );+ expect(+ readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8"),+ ).not.toBe("stale\n");+ expect(+ readFileSync(join(vault, "AI Wiki", "_OPEN_SECOND_BRAIN.md"), "utf8"),+ ).not.toBe("stale\n");+ });+});++describe("bootstrapBrain β missing machine config", () => {+ test("throws an error naming `o2b init` when the plugin config does not exist", () => {+ const missing = join(configHome, "does-not-exist.yaml");+ expect(() => bootstrapBrain(vault, { configPath: missing })).toThrow(+ /o2b init/,+ );+ });++ test("error message includes the resolved config path", () => {+ const missing = join(configHome, "phantom-cfg.yaml");+ let captured: Error | null = null;+ try {+ bootstrapBrain(vault, { configPath: missing });+ } catch (err) {+ captured = err as Error;+ }+ expect(captured).not.toBeNull();+ expect(captured?.message).toContain(missing);+ });+});++describe("bootstrapBrain β _BRAIN.md compliance ceiling", () => {+ test("rendered Brain manual is strictly under 200 lines", () => {+ bootstrapBrain(vault, { configPath });+ const manual = readFileSync(join(vault, "Brain", "_BRAIN.md"), "utf8");+ // Count newline-terminated lines plus any trailing fragment. A file+ // ending in `\n` and one ending without it should both report the+ // user-visible line count.+ const lines = manual.split("\n");+ const lineCount =+ manual.endsWith("\n") && lines.length > 0+ ? lines.length - 1+ : lines.length;+ expect(lineCount).toBeLessThan(200);+ });+});diff --git a/tests/core/brain.log.test.ts b/tests/core/brain.log.test.tsnew file mode 100644index 00000000..141fccf4--- /dev/null+++ b/tests/core/brain.log.test.ts@@ -0,0 +1,239 @@+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 {+ appendLogEvent,+ parseLogDay,+ type BrainLogEntry,+} from "../../src/core/brain/log.ts";+import { brainDirs, logPath } from "../../src/core/brain/paths.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-log-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("appendLogEvent β create-on-first-event", () => {+ test("creates the file with a canonical header and the first event", () => {+ const event: BrainLogEntry = {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "dream",+ body: {+ run_id: "dream-2026-05-14-104200",+ input_signals: "7",+ new_unconfirmed: ["[[pref-no-internal-abbrev]] (signal_balance: -3)"],+ confirmed: "0",+ retired: "0",+ },+ };+ const res = appendLogEvent(tmp, event);+ expect(res.logPath).toBe(logPath(tmp, "2026-05-14"));+ expect(existsSync(res.logPath)).toBe(true);+ const bytes = readFileSync(res.logPath, "utf8");+ expect(bytes).toContain("---\nkind: brain-log\ndate: 2026-05-14");+ expect(bytes).toContain("tags: [brain, brain/log]");+ expect(bytes).toContain("# Brain log β 2026-05-14");+ expect(bytes).toContain("## 10:42:00Z β dream");+ expect(bytes).toContain("- run_id: dream-2026-05-14-104200");+ expect(bytes).toContain("- new_unconfirmed:");+ expect(bytes).toContain(" - [[pref-no-internal-abbrev]] (signal_balance: -3)");+ });++ test("parseLogDay returns the single event", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "dream",+ body: { run_id: "dream-2026-05-14-104200", confirmed: "0" },+ });+ const { entries, warnings } = parseLogDay(tmp, "2026-05-14");+ expect(warnings).toEqual([]);+ expect(entries).toHaveLength(1);+ expect(entries[0]!.eventType).toBe("dream");+ expect(entries[0]!.timestamp).toBe("2026-05-14T10:42:00Z");+ expect(entries[0]!.body["run_id"]).toBe("dream-2026-05-14-104200");+ });++ test("parseLogDay returns [] for a missing file (no Brain log for that day)", () => {+ const { entries, warnings } = parseLogDay(tmp, "2099-01-01");+ expect(entries).toEqual([]);+ expect(warnings).toEqual([]);+ });+});++describe("appendLogEvent β multi-event same day", () => {+ test("two appends produce two parseable events in stable order", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "dream",+ body: { run_id: "dream-2026-05-14-104200" },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T14:22:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-no-internal-abbrev]]",+ artifact: "[[Daily/2026.05.14#section-blog-post]]",+ agent: "claude",+ result: "applied",+ note: "Expanded OSB on first use.",+ },+ });+ const { entries, warnings } = parseLogDay(tmp, "2026-05-14");+ expect(warnings).toEqual([]);+ expect(entries).toHaveLength(2);+ expect(entries[0]!.eventType).toBe("dream");+ expect(entries[1]!.eventType).toBe("apply-evidence");+ expect(entries[1]!.body["result"]).toBe("applied");+ expect(entries[1]!.body["preference"]).toBe("[[pref-no-internal-abbrev]]");+ });++ test("two events at the exact same UTC second land in order of call", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "feedback",+ body: { signal: "[[sig-a]]" },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "feedback",+ body: { signal: "[[sig-b]]" },+ });+ const { entries } = parseLogDay(tmp, "2026-05-14");+ expect(entries).toHaveLength(2);+ expect(entries[0]!.body["signal"]).toBe("[[sig-a]]");+ expect(entries[1]!.body["signal"]).toBe("[[sig-b]]");+ });++ test("the original file bytes are preserved verbatim across appends (append-only)", () => {+ const a = appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "dream",+ body: { run_id: "dream-2026-05-14-104200" },+ });+ const firstBytes = readFileSync(a.logPath, "utf8");+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T14:22:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-foo]]",+ artifact: "[[bar]]",+ agent: "claude",+ result: "applied",+ },+ });+ const secondBytes = readFileSync(a.logPath, "utf8");+ // The second file must start with the first file's full content+ // (trailing whitespace tolerated) β i.e. nothing earlier was edited.+ const stripTrailing = (s: string): string => s.replace(/\s+$/, "");+ expect(secondBytes.startsWith(stripTrailing(firstBytes))).toBe(true);+ expect(secondBytes.length).toBeGreaterThan(firstBytes.length);+ });+});++describe("parseLogDay β malformed entry tolerance", () => {+ test("returns only the valid entries and reports warnings for the rest", () => {+ const dirs = brainDirs(tmp);+ mkdirSync(dirs.log, { recursive: true });+ const path = logPath(tmp, "2026-05-14");+ const content = [+ "---",+ "kind: brain-log",+ "date: 2026-05-14",+ "tags: [brain, brain/log]",+ "---",+ "",+ "# Brain log β 2026-05-14",+ "",+ "## 10:42:00Z β dream",+ "- run_id: dream-2026-05-14-104200",+ "- confirmed: 0",+ "",+ "## 11:00:00 NOT-A-VALID-HEADER", // broken header+ "- this: should be ignored",+ "",+ "## 12:00:00Z β apply-evidence",+ "- preference: [[pref-foo]]",+ "- artifact: [[bar]]",+ "- agent: claude",+ "- result: applied",+ "",+ "## 13:00:00Z β totally-bogus-kind", // unknown event kind+ "- foo: bar",+ "",+ "## 14:00:00Z β feedback",+ "- signal: [[sig-x]]",+ "garbage line that is not a bullet", // malformed bullet inside a valid block+ "- topic: foo",+ ].join("\n");+ writeFileSync(path, content, "utf8");++ const { entries, warnings } = parseLogDay(tmp, "2026-05-14");+ // Only the three well-formed entries (dream, apply-evidence,+ // feedback) survive.+ expect(entries).toHaveLength(3);+ expect(entries.map((e) => e.eventType)).toEqual([+ "dream",+ "apply-evidence",+ "feedback",+ ]);+ // The broken header and bogus kind both produce warnings; the+ // stray bullet does too.+ expect(warnings.length).toBeGreaterThanOrEqual(2);+ const messages = warnings.map((w) => w.message).join("\n");+ expect(messages).toMatch(/malformed event header|unknown event kind/);+ });+});++describe("ISO timestamp round-trip", () => {+ test("appended timestamp parses back verbatim", () => {+ const ts = "2026-05-14T07:08:09Z";+ appendLogEvent(tmp, {+ timestamp: ts,+ eventType: "promote",+ body: { preference: "[[pref-foo]]" },+ });+ const { entries } = parseLogDay(tmp, "2026-05-14");+ expect(entries).toHaveLength(1);+ expect(entries[0]!.timestamp).toBe(ts);+ });++ test("sub-second precision is truncated to seconds in the heading", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T07:08:09.123Z",+ eventType: "promote",+ body: { preference: "[[pref-foo]]" },+ });+ const { entries } = parseLogDay(tmp, "2026-05-14");+ expect(entries).toHaveLength(1);+ // The serialised form drops sub-seconds; the parser reconstructs+ // a clean `HH:MM:SSZ`.+ expect(entries[0]!.timestamp).toBe("2026-05-14T07:08:09Z");+ });++ test("invalid timestamp shape is rejected at append time", () => {+ expect(() =>+ appendLogEvent(tmp, {+ timestamp: "2026-05-14 10:42:00",+ eventType: "promote",+ body: {},+ }),+ ).toThrow(/ISO-8601 UTC/);+ });++ test("unknown event kind is rejected at append time", () => {+ expect(() =>+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:42:00Z",+ eventType: "totally-bogus" as unknown as "dream",+ body: {},+ }),+ ).toThrow(/unknown event kind/);+ });+});diff --git a/tests/core/brain.paths.test.ts b/tests/core/brain.paths.test.tsnew file mode 100644index 00000000..b0f3a391--- /dev/null+++ b/tests/core/brain.paths.test.ts@@ -0,0 +1,364 @@+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 {+ allocateSlug,+ brainConfigPath,+ brainDirs,+ brainManualPath,+ brainVaultRelative,+ logPath,+ preferencePath,+ processedSignalPath,+ retiredPath,+ signalPath,+ snapshotPath,+ snapshotsDir,+ validateIsoDate,+ validateRunId,+ validateSlug,+} from "../../src/core/brain/paths.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-paths-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++describe("brainDirs", () => {+ test("composes the canonical Brain/ layout", () => {+ const dirs = brainDirs("/vault");+ expect(dirs.brain).toBe(join("/vault", "Brain"));+ expect(dirs.inbox).toBe(join("/vault", "Brain", "inbox"));+ expect(dirs.processed).toBe(join("/vault", "Brain", "inbox", "processed"));+ expect(dirs.preferences).toBe(join("/vault", "Brain", "preferences"));+ expect(dirs.retired).toBe(join("/vault", "Brain", "retired"));+ expect(dirs.log).toBe(join("/vault", "Brain", "log"));+ expect(dirs.snapshots).toBe(join("/vault", "Brain", ".snapshots"));+ });+});++describe("path constructors", () => {+ test("brainConfigPath / brainManualPath", () => {+ expect(brainConfigPath("/v")).toBe(join("/v", "Brain", "_brain.yaml"));+ expect(brainManualPath("/v")).toBe(join("/v", "Brain", "_BRAIN.md"));+ });++ test("signalPath, processedSignalPath", () => {+ expect(signalPath("/v", "2026-05-14", "no-internal-abbrev")).toBe(+ join("/v", "Brain", "inbox", "sig-2026-05-14-no-internal-abbrev.md"),+ );+ expect(processedSignalPath("/v", "2026-05-14", "no-internal-abbrev")).toBe(+ join(+ "/v",+ "Brain",+ "inbox",+ "processed",+ "sig-2026-05-14-no-internal-abbrev.md",+ ),+ );+ });++ test("preferencePath / retiredPath / logPath / snapshotsDir / snapshotPath", () => {+ expect(preferencePath("/v", "no-internal-abbrev")).toBe(+ join("/v", "Brain", "preferences", "pref-no-internal-abbrev.md"),+ );+ expect(retiredPath("/v", "no-internal-abbrev")).toBe(+ join("/v", "Brain", "retired", "ret-no-internal-abbrev.md"),+ );+ expect(logPath("/v", "2026-05-14")).toBe(+ join("/v", "Brain", "log", "2026-05-14.md"),+ );+ expect(snapshotsDir("/v")).toBe(join("/v", "Brain", ".snapshots"));+ expect(snapshotPath("/v", "dream-2026-05-14-104200")).toBe(+ join("/v", "Brain", ".snapshots", "dream-2026-05-14-104200.tar.zst"),+ );+ });++ test("signalPath validates date format", () => {+ expect(() => signalPath("/v", "2026.05.14", "slug")).toThrow();+ expect(() => signalPath("/v", "14-05-2026", "slug")).toThrow();+ expect(() => signalPath("/v", "2026-13-01", "slug")).toThrow();+ });++ test("logPath validates date", () => {+ expect(() => logPath("/v", "nope")).toThrow();+ expect(() => logPath("/v", "2025-02-29")).toThrow();+ });+});++describe("validateSlug", () => {+ test("accepts plain slugs", () => {+ expect(validateSlug("no-internal-abbrev")).toBe("no-internal-abbrev");+ expect(validateSlug("alpha_beta-2")).toBe("alpha_beta-2");+ });++ test("rejects path separators", () => {+ expect(() => validateSlug("a/b")).toThrow(/path separators/);+ expect(() => validateSlug("a\\b")).toThrow(/path separators/);+ });++ test("rejects traversal", () => {+ expect(() => validateSlug("..")).toThrow(/traversal/);+ expect(() => validateSlug("..-evil")).toThrow(/traversal/);+ expect(() => validateSlug("evil-..")).toThrow(/traversal/);+ });++ test("rejects empty", () => {+ expect(() => validateSlug("")).toThrow();+ expect(() => validateSlug(" ")).toThrow();+ });++ test("trims whitespace", () => {+ expect(validateSlug(" ok-slug ")).toBe("ok-slug");+ });++ test("rejects Windows-reserved basenames", () => {+ expect(() => validateSlug("CON")).toThrow(/Windows-reserved/);+ expect(() => validateSlug("nul.md")).toThrow(/Windows-reserved/);+ });++ test("rejects Windows-invalid filename characters", () => {+ expect(() => validateSlug("slug:with-colon")).toThrow(/invalid character/);+ expect(() => validateSlug("slug*with-star")).toThrow(/invalid character/);+ expect(() => validateSlug('slug"quote')).toThrow(/invalid character/);+ expect(() => validateSlug("slug<lt")).toThrow(/invalid character/);+ expect(() => validateSlug("slug>gt")).toThrow(/invalid character/);+ expect(() => validateSlug("slug|pipe")).toThrow(/invalid character/);+ expect(() => validateSlug("slug?question")).toThrow(/invalid character/);+ });++ test("rejects ASCII control characters in slug", () => {+ expect(() => validateSlug("slug\x00null")).toThrow(/invalid character/);+ expect(() => validateSlug("slug\nnewline")).toThrow(/invalid character/);+ expect(() => validateSlug("slug\x1Fus")).toThrow(/invalid character/);+ });+});++describe("validateIsoDate", () => {+ test("accepts well-formed ISO dates", () => {+ expect(validateIsoDate("2026-05-14")).toBe("2026-05-14");+ expect(validateIsoDate("2024-02-29")).toBe("2024-02-29");+ });++ test("rejects bad shapes", () => {+ expect(() => validateIsoDate("nope")).toThrow(/format/);+ expect(() => validateIsoDate("2026/05/14")).toThrow();+ });++ test("rejects impossible calendar dates", () => {+ expect(() => validateIsoDate("2025-02-29")).toThrow(/valid calendar date/);+ expect(() => validateIsoDate("2026-13-01")).toThrow(/valid calendar date/);+ });+});++describe("validateRunId", () => {+ test("accepts dream run ids", () => {+ expect(validateRunId("dream-2026-05-14-104200")).toBe(+ "dream-2026-05-14-104200",+ );+ });++ test("rejects empty / separators / traversal", () => {+ expect(() => validateRunId("")).toThrow();+ expect(() => validateRunId("a/b")).toThrow();+ expect(() => validateRunId("..")).toThrow();+ expect(() => validateRunId("dream..2026")).toThrow();+ });++ test("rejects leading dot", () => {+ expect(() => validateRunId(".hidden")).toThrow();+ });++ test("rejects Windows-reserved", () => {+ expect(() => validateRunId("con")).toThrow(/Windows-reserved/);+ });+});++describe("path-safety", () => {+ test("signalPath rejects traversal slugs (defense in depth)", () => {+ expect(() => signalPath("/v", "2026-05-14", "../escape")).toThrow();+ });++ test("preferencePath rejects path-separator slug", () => {+ expect(() => preferencePath("/v", "a/b")).toThrow();+ });++ test("snapshotPath rejects bogus run_id", () => {+ expect(() => snapshotPath("/v", "../etc/passwd")).toThrow();+ expect(() => snapshotPath("/v", "")).toThrow();+ });+});++describe("brainVaultRelative", () => {+ test("renders posix-style relative path", () => {+ const abs = join("/vault", "Brain", "preferences", "pref-x.md");+ expect(brainVaultRelative(abs, "/vault")).toBe(+ "Brain/preferences/pref-x.md",+ );+ });+});++describe("allocateSlug β collision allocator", () => {+ test("returns bare slug when target is free", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ const result = allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "sig-2026-05-14",+ slug: "no-internal-abbrev",+ });+ expect(result.slug).toBe("no-internal-abbrev");+ expect(result.suffix).toBeNull();+ expect(result.path).toBe(+ join(targetDir, "sig-2026-05-14-no-internal-abbrev.md"),+ );+ });++ test("appends -2 on first collision", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ writeFileSync(+ join(targetDir, "sig-2026-05-14-no-internal-abbrev.md"),+ "stub",+ "utf8",+ );++ const result = allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "sig-2026-05-14",+ slug: "no-internal-abbrev",+ });+ expect(result.slug).toBe("no-internal-abbrev-2");+ expect(result.suffix).toBe(2);+ expect(result.path).toBe(+ join(targetDir, "sig-2026-05-14-no-internal-abbrev-2.md"),+ );+ });++ test("appends -3 on second collision", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ writeFileSync(+ join(targetDir, "sig-2026-05-14-no-internal-abbrev.md"),+ "stub",+ "utf8",+ );+ writeFileSync(+ join(targetDir, "sig-2026-05-14-no-internal-abbrev-2.md"),+ "stub",+ "utf8",+ );++ const result = allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "sig-2026-05-14",+ slug: "no-internal-abbrev",+ });+ expect(result.slug).toBe("no-internal-abbrev-3");+ expect(result.suffix).toBe(3);+ });++ test("each successive call increments deterministically", () => {+ const targetDir = join(tmp, "Brain", "preferences");+ mkdirSync(targetDir, { recursive: true });++ const expected: Array<readonly [string, number | null]> = [+ ["foo", null],+ ["foo-2", 2],+ ["foo-3", 3],+ ["foo-4", 4],+ ];+ for (const [slug, suffix] of expected) {+ const r = allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "pref",+ slug: "foo",+ });+ expect(r.slug).toBe(slug);+ expect(r.suffix).toBe(suffix);+ // Create the file so the next iteration sees a collision.+ writeFileSync(r.path, "stub", "utf8");+ }+ });++ test("rejects slug with traversal up-front", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ expect(() =>+ allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "sig-2026-05-14",+ slug: "..",+ }),+ ).toThrow();+ });++ test("rejects empty or path-dirty prefix", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ expect(() =>+ allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "",+ slug: "ok",+ }),+ ).toThrow(/prefix/);+ expect(() =>+ allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "evil/dir",+ slug: "ok",+ }),+ ).toThrow(/prefix/);+ });++ test("aborts when maxAttempts exhausted instead of looping forever", () => {+ const targetDir = join(tmp, "Brain", "inbox");+ mkdirSync(targetDir, { recursive: true });+ // Seed two collisions then cap at 2.+ writeFileSync(join(targetDir, "sig-stub-x.md"), "1", "utf8");+ writeFileSync(join(targetDir, "sig-stub-x-2.md"), "1", "utf8");+ expect(() =>+ allocateSlug({+ vault: tmp,+ targetDir,+ prefix: "sig-stub",+ slug: "x",+ maxAttempts: 2,+ }),+ ).toThrow(/could not find a free name/);+ });++ test("refuses a targetDir outside the vault", () => {+ // Pick a sibling path that exists (tmpdir itself) so the realpath+ // probe doesn't short-circuit before lexical comparison; the lexical+ // check still rejects it because it's not under tmp/.+ const outside = mkdtempSync(join(tmpdir(), "o2b-brain-outside-"));+ try {+ expect(() =>+ allocateSlug({+ vault: tmp,+ targetDir: outside,+ prefix: "sig",+ slug: "x",+ }),+ ).toThrow(/path escapes vault/);+ } finally {+ rmSync(outside, { recursive: true, force: true });+ }+ });+});diff --git a/tests/core/brain.pin.test.ts b/tests/core/brain.pin.test.tsnew file mode 100644index 00000000..0edc678b--- /dev/null+++ b/tests/core/brain.pin.test.ts@@ -0,0 +1,185 @@+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 { isPinned, setPinned } from "../../src/core/brain/pin.ts";+import { parseLogDay } from "../../src/core/brain/log.ts";+import {+ parsePreference,+ writePreference,+} from "../../src/core/brain/preference.ts";+import { BrainPreferenceNotFoundError } from "../../src/core/brain/apply-evidence.ts";+import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import type { BrainPreference } from "../../src/core/brain/types.ts";++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-pin-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-pin-cfg-"));+ 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 });+});++function makePref(slug: string, pinned: boolean): string {+ const r = writePreference(vault, {+ slug,+ topic: slug,+ principle: `Rule for ${slug}`,+ created_at: "2026-05-14T10:42:00Z",+ unconfirmed_until: "2026-05-28T10:42:00Z",+ status: "unconfirmed",+ evidenced_by: [`[[sig-2026-05-13-${slug}]]`],+ pinned,+ });+ return r.path;+}++describe("setPinned β happy paths", () => {+ test("false β true: changed: true, log gets a pin event, frontmatter flipped", () => {+ const path = makePref("flippable", false);+ const before = parsePreference(path);+ expect(before.pinned).toBe(false);++ const res = setPinned(vault, "flippable", true, {+ now: new Date("2026-05-14T07:00:00Z"),+ agent: "claude",+ });+ expect(res.changed).toBe(true);+ expect(res.path).toBe(path);++ const after = parsePreference(path);+ expect(after.pinned).toBe(true);++ const { entries } = parseLogDay(vault, "2026-05-14");+ expect(entries).toHaveLength(1);+ expect(entries[0]!.eventType).toBe("pin");+ expect(entries[0]!.body["preference"]).toBe("[[pref-flippable]]");+ expect(entries[0]!.body["agent"]).toBe("claude");+ });++ test("true β false: changed: true, log gets an unpin event", () => {+ const path = makePref("unpinnable", true);+ const res = setPinned(vault, "unpinnable", false, {+ now: new Date("2026-05-14T08:00:00Z"),+ });+ expect(res.changed).toBe(true);+ const reparsed = parsePreference(path);+ expect(reparsed.pinned).toBe(false);++ const { entries } = parseLogDay(vault, "2026-05-14");+ expect(entries).toHaveLength(1);+ expect(entries[0]!.eventType).toBe("unpin");+ });++ test("accepts both 'pref-foo' and 'foo' forms", () => {+ makePref("either-form", false);+ const a = setPinned(vault, "pref-either-form", true, {+ now: new Date("2026-05-14T09:00:00Z"),+ });+ expect(a.changed).toBe(true);+ // Idempotent path: prefixed form should still resolve to same file.+ const b = setPinned(vault, "either-form", true, {+ now: new Date("2026-05-14T09:00:01Z"),+ });+ expect(b.changed).toBe(false);+ });+});++describe("setPinned β idempotency", () => {+ test("true β true: changed: false and no log event", () => {+ makePref("already-pinned", true);++ const res = setPinned(vault, "already-pinned", true, {+ now: new Date("2026-05-14T10:00:00Z"),+ });+ expect(res.changed).toBe(false);++ // The log file should not have been created on an idempotent+ // no-op β the appender writes the canonical header on first+ // event, so a missing file is the cleanest assertion.+ const { entries } = parseLogDay(vault, "2026-05-14");+ expect(entries).toEqual([]);+ });++ test("false β false: changed: false and no log event", () => {+ makePref("never-pinned", false);+ const res = setPinned(vault, "never-pinned", false, {+ now: new Date("2026-05-14T10:00:00Z"),+ });+ expect(res.changed).toBe(false);+ const { entries } = parseLogDay(vault, "2026-05-14");+ expect(entries).toEqual([]);+ });+});++describe("setPinned β body preservation", () => {+ test("preference body (How to apply section, etc) is unchanged", () => {+ const path = makePref("preserve-body", false);+ const before = readFileSync(path, "utf8");+ const bodyBefore = before.split("---\n").slice(2).join("---\n");++ setPinned(vault, "preserve-body", true, {+ now: new Date("2026-05-14T10:00:00Z"),+ });++ const after = readFileSync(path, "utf8");+ const bodyAfter = after.split("---\n").slice(2).join("---\n");+ expect(bodyAfter).toBe(bodyBefore);+ });+});++describe("setPinned β error paths", () => {+ test("missing preference throws BrainPreferenceNotFoundError", () => {+ expect(() => setPinned(vault, "does-not-exist", true)).toThrow(+ BrainPreferenceNotFoundError,+ );+ });++ test("empty pref_id throws", () => {+ expect(() => setPinned(vault, "", true)).toThrow(/missing field|empty slug/);+ });+});++describe("isPinned β accessor", () => {+ test("returns false on a parsed preference whose frontmatter omits pinned", () => {+ // Construct an object that mimics a parsed preference with+ // pinned: false (the parser's default).+ const fake: BrainPreference = Object.freeze({+ kind: "brain-preference",+ id: "pref-x",+ created_at: "2026-05-14T10:42:00Z",+ confirmed_at: null,+ unconfirmed_until: "2026-05-28T10:42:00Z",+ tags: ["brain"],+ topic: "x",+ status: "unconfirmed",+ principle: "...",+ evidenced_by: [],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence: "low",+ pinned: false,+ });+ expect(isPinned(fake)).toBe(false);+ });++ test("returns true when frontmatter explicitly sets pinned: true", () => {+ makePref("explicit-pinned", true);+ const parsed = parsePreference(+ `${vault}/Brain/preferences/pref-explicit-pinned.md`,+ );+ expect(isPinned(parsed)).toBe(true);+ });+});diff --git a/tests/core/brain.policy.test.ts b/tests/core/brain.policy.test.tsnew file mode 100644index 00000000..fc02cc7d--- /dev/null+++ b/tests/core/brain.policy.test.ts@@ -0,0 +1,330 @@+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 {+ BRAIN_CONFIG_SUPPORTED_VERSIONS,+ BrainConfigError,+ DEFAULT_BRAIN_CONFIG,+ DEFAULT_BRAIN_CONFIG_YAML,+ loadBrainConfig,+ loadBrainConfigDetailed,+ parseBrainYaml,+ validateBrainConfig,+ validateBrainConfigDetailed,+} from "../../src/core/brain/policy.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-policy-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function writeBrainYaml(vault: string, body: string): string {+ const brainDir = join(vault, "Brain");+ mkdirSync(brainDir, { recursive: true });+ const path = join(brainDir, "_brain.yaml");+ writeFileSync(path, body, "utf8");+ return path;+}++describe("DEFAULT_BRAIN_CONFIG", () => {+ test("matches the values listed in Β§10 of the design doc", () => {+ expect(DEFAULT_BRAIN_CONFIG.schema_version).toBe(1);+ expect(DEFAULT_BRAIN_CONFIG.dream.candidate_threshold).toBe(3);+ expect(DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days).toBe(14);+ expect(DEFAULT_BRAIN_CONFIG.dream.contradiction_window_days).toBe(14);+ expect(DEFAULT_BRAIN_CONFIG.retire.stale_evidence_days).toBe(90);+ expect(DEFAULT_BRAIN_CONFIG.confidence.low_max_applied).toBe(2);+ expect(DEFAULT_BRAIN_CONFIG.confidence.high_min_applied).toBe(10);+ expect(DEFAULT_BRAIN_CONFIG.confidence.high_freshness_factor).toBe(0.8);+ expect(DEFAULT_BRAIN_CONFIG.snapshots.retention_count).toBe(10);+ });++ test("BRAIN_CONFIG_SUPPORTED_VERSIONS includes 1", () => {+ expect(BRAIN_CONFIG_SUPPORTED_VERSIONS).toContain(1);+ });++ test("DEFAULT_BRAIN_CONFIG_YAML parses back into a valid config", () => {+ const parsed = parseBrainYaml(DEFAULT_BRAIN_CONFIG_YAML);+ const config = validateBrainConfig(parsed, "<default>");+ expect(config).toEqual(DEFAULT_BRAIN_CONFIG);+ });+});++describe("validateBrainConfig β happy path", () => {+ test("accepts the default config", () => {+ const config = validateBrainConfig(+ JSON.parse(JSON.stringify(DEFAULT_BRAIN_CONFIG)),+ "<test>",+ );+ expect(config.schema_version).toBe(1);+ expect(config.snapshots.retention_count).toBe(10);+ });++ test("fills missing blocks from defaults", () => {+ const config = validateBrainConfig({ schema_version: 1 }, "<test>");+ expect(config.dream.candidate_threshold).toBe(3);+ expect(config.retire.stale_evidence_days).toBe(90);+ expect(config.confidence.high_freshness_factor).toBe(0.8);+ expect(config.snapshots.retention_count).toBe(10);+ });++ test("merges single overridden field with defaults", () => {+ const config = validateBrainConfig(+ {+ schema_version: 1,+ dream: { candidate_threshold: 5 },+ },+ "<test>",+ );+ expect(config.dream.candidate_threshold).toBe(5);+ // Untouched fields fall back to defaults.+ expect(config.dream.unconfirmed_window_days).toBe(14);+ });+});++describe("validateBrainConfig β error cases", () => {+ test("missing schema_version β error naming the field", () => {+ expect(() => validateBrainConfig({}, "<test>")).toThrow(BrainConfigError);+ try {+ validateBrainConfig({}, "<test>");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainConfigError);+ expect((err as BrainConfigError).field).toBe("schema_version");+ }+ });++ test("unsupported schema_version β error", () => {+ expect(() =>+ validateBrainConfig({ schema_version: 99 }, "<test>"),+ ).toThrow(/schema_version/);+ });++ test("non-integer schema_version β error", () => {+ expect(() =>+ validateBrainConfig({ schema_version: "1" }, "<test>"),+ ).toThrow(/schema_version/);+ expect(() =>+ validateBrainConfig({ schema_version: 1.5 }, "<test>"),+ ).toThrow(/schema_version/);+ });++ test("negative threshold β error naming the field", () => {+ try {+ validateBrainConfig(+ { schema_version: 1, dream: { candidate_threshold: -1 } },+ "<test>",+ );+ throw new Error("should have thrown");+ } catch (err) {+ expect(err).toBeInstanceOf(BrainConfigError);+ expect((err as BrainConfigError).field).toBe("dream.candidate_threshold");+ }+ });++ test("non-integer threshold β error", () => {+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, dream: { candidate_threshold: 3.5 } },+ "<test>",+ ),+ ).toThrow(/positive integer/);+ });++ test("zero candidate_threshold β error (must be positive)", () => {+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, dream: { candidate_threshold: 0 } },+ "<test>",+ ),+ ).toThrow(/positive integer/);+ });++ test("high_freshness_factor <= 0 β error", () => {+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, confidence: { high_freshness_factor: 0 } },+ "<test>",+ ),+ ).toThrow(/\(0, 1\]/);+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, confidence: { high_freshness_factor: -0.1 } },+ "<test>",+ ),+ ).toThrow(/\(0, 1\]/);+ });++ test("high_freshness_factor > 1 β error", () => {+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, confidence: { high_freshness_factor: 1.5 } },+ "<test>",+ ),+ ).toThrow(/\(0, 1\]/);+ });++ test("high_freshness_factor == 1 is accepted (inclusive upper bound)", () => {+ const cfg = validateBrainConfig(+ { schema_version: 1, confidence: { high_freshness_factor: 1 } },+ "<test>",+ );+ expect(cfg.confidence.high_freshness_factor).toBe(1);+ });++ test("snapshots.retention_count must be positive integer", () => {+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, snapshots: { retention_count: 0 } },+ "<test>",+ ),+ ).toThrow(/positive integer/);+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, snapshots: { retention_count: -5 } },+ "<test>",+ ),+ ).toThrow(/positive integer/);+ expect(() =>+ validateBrainConfig(+ { schema_version: 1, snapshots: { retention_count: 1.5 } },+ "<test>",+ ),+ ).toThrow(/positive integer/);+ });++ test("non-object root β error", () => {+ expect(() => validateBrainConfig(null, "<test>")).toThrow(BrainConfigError);+ expect(() => validateBrainConfig(42, "<test>")).toThrow(BrainConfigError);+ expect(() => validateBrainConfig([], "<test>")).toThrow(BrainConfigError);+ });++ test("non-object block β error", () => {+ expect(() =>+ validateBrainConfig({ schema_version: 1, dream: 5 }, "<test>"),+ ).toThrow(/dream/);+ });++ test("confidence.low_max_applied = 0 is allowed (non-negative)", () => {+ const cfg = validateBrainConfig(+ { schema_version: 1, confidence: { low_max_applied: 0 } },+ "<test>",+ );+ expect(cfg.confidence.low_max_applied).toBe(0);+ });+});++describe("validateBrainConfig β warnings (forward-compat)", () => {+ test("unknown top-level keys produce warnings, not errors", () => {+ const result = validateBrainConfigDetailed(+ { schema_version: 1, future_field: "x", another: 42 },+ "<test>",+ );+ expect(result.warnings.length).toBe(2);+ expect(result.warnings.map((w) => w.message).join("\n")).toContain(+ "future_field",+ );+ expect(result.warnings.map((w) => w.message).join("\n")).toContain(+ "another",+ );+ expect(result.config.schema_version).toBe(1);+ });++ test("no warnings on a fully-known config", () => {+ const result = validateBrainConfigDetailed(+ JSON.parse(JSON.stringify(DEFAULT_BRAIN_CONFIG)),+ "<test>",+ );+ expect(result.warnings.length).toBe(0);+ });+});++describe("loadBrainConfig β filesystem integration", () => {+ test("loads a well-formed config from <vault>/Brain/_brain.yaml", () => {+ writeBrainYaml(tmp, DEFAULT_BRAIN_CONFIG_YAML);+ const cfg = loadBrainConfig(tmp);+ expect(cfg).toEqual(DEFAULT_BRAIN_CONFIG);+ });++ test("loadBrainConfigDetailed returns warnings + path", () => {+ writeBrainYaml(+ tmp,+ `${DEFAULT_BRAIN_CONFIG_YAML}\nfuture_field: 1\n`,+ );+ const result = loadBrainConfigDetailed(tmp);+ expect(result.path).toBe(join(tmp, "Brain", "_brain.yaml"));+ expect(result.warnings.length).toBe(1);+ expect(result.warnings[0]!.message).toContain("future_field");+ });++ test("missing file β BrainConfigError pointing at init", () => {+ expect(() => loadBrainConfig(tmp)).toThrow(/o2b brain init/);+ });++ test("malformed YAML β BrainConfigError", () => {+ writeBrainYaml(tmp, "schema_version: 1\nthis is not yaml: [unbalanced\n");+ // Top-level key with an inline-array-like value is parsed as a string,+ // so this particular text actually parses. Use a real shape error: a+ // child line at the top level (no parent block).+ writeBrainYaml(tmp, "schema_version: 1\n nested_without_parent: 1\n");+ expect(() => loadBrainConfig(tmp)).toThrow(BrainConfigError);+ });++ test("non-object dream block β BrainConfigError", () => {+ writeBrainYaml(tmp, "schema_version: 1\ndream: 5\n");+ expect(() => loadBrainConfig(tmp)).toThrow(/dream/);+ });+});++describe("parseBrainYaml", () => {+ test("parses scalars: numbers, floats, quoted strings, booleans, null", () => {+ const parsed = parseBrainYaml(+ `schema_version: 1\nint_val: 42\nfloat_val: 0.8\nstr_val: "hello"\nbool_t: true\nbool_f: false\nnone: null\n`,+ );+ expect(parsed["schema_version"]).toBe(1);+ expect(parsed["int_val"]).toBe(42);+ expect(parsed["float_val"]).toBe(0.8);+ expect(parsed["str_val"]).toBe("hello");+ expect(parsed["bool_t"]).toBe(true);+ expect(parsed["bool_f"]).toBe(false);+ expect(parsed["none"]).toBeNull();+ });++ test("parses one-level indented blocks", () => {+ const parsed = parseBrainYaml(+ `schema_version: 1\ndream:\n candidate_threshold: 3\n unconfirmed_window_days: 14\n`,+ );+ expect(parsed["dream"]).toEqual({+ candidate_threshold: 3,+ unconfirmed_window_days: 14,+ });+ });++ test("strips comments and blank lines", () => {+ const parsed = parseBrainYaml(+ `# comment\nschema_version: 1\n\n# another\ndream:\n # nested comment\n candidate_threshold: 3\n`,+ );+ expect(parsed["schema_version"]).toBe(1);+ expect(parsed["dream"]).toEqual({ candidate_threshold: 3 });+ });++ test("rejects nested blocks deeper than one level", () => {+ expect(() =>+ parseBrainYaml(+ `top:\n middle:\n leaf: 1\n`,+ ),+ ).toThrow(/deeper than one level/);+ });++ test("rejects duplicate top-level key", () => {+ expect(() =>+ parseBrainYaml(`schema_version: 1\nschema_version: 2\n`),+ ).toThrow(/duplicate/);+ });+});diff --git a/tests/core/brain.preference.test.ts b/tests/core/brain.preference.test.tsnew file mode 100644index 00000000..a8ebc3c0--- /dev/null+++ b/tests/core/brain.preference.test.ts@@ -0,0 +1,327 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ BrainStatusFolderMismatchError,+ moveToRetired,+ parsePreference,+ parseRetired,+ writePreference,+ type WritePreferenceInput,+} from "../../src/core/brain/preference.ts";+import {+ brainDirs,+ preferencePath,+ retiredPath,+} from "../../src/core/brain/paths.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-pref-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function basePrefInput(+ overrides: Partial<WritePreferenceInput> = {},+): WritePreferenceInput {+ return {+ slug: "no-internal-abbrev",+ topic: "no-internal-abbrev",+ principle:+ "Do not use internal abbreviations in user-facing copy unless explained first",+ created_at: "2026-05-14T10:42:00Z",+ unconfirmed_until: "2026-05-28T10:42:00Z",+ status: "unconfirmed",+ evidenced_by: [+ "[[sig-2026-05-13-no-internal-abbrev]]",+ "[[sig-2026-05-14-no-internal-abbrev]]",+ ],+ scope: "writing",+ confirmed_at: null,+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence: "low",+ pinned: false,+ howToApply:+ "Expand acronyms on first use in any user-facing copy.",+ ...overrides,+ };+}++describe("writePreference + parsePreference", () => {+ test("parses an unconfirmed preference correctly", () => {+ const res = writePreference(tmp, basePrefInput());+ expect(res.id).toBe("pref-no-internal-abbrev");++ const parsed = parsePreference(res.path);+ expect(parsed.kind).toBe("brain-preference");+ expect(parsed.status).toBe("unconfirmed");+ expect(parsed.confirmed_at).toBeNull();+ expect(parsed.unconfirmed_until).toBe("2026-05-28T10:42:00Z");+ expect(parsed.evidenced_by).toEqual([+ "[[sig-2026-05-13-no-internal-abbrev]]",+ "[[sig-2026-05-14-no-internal-abbrev]]",+ ]);+ expect(parsed.applied_count).toBe(0);+ expect(parsed.violated_count).toBe(0);+ expect(parsed.last_evidence_at).toBeNull();+ expect(parsed.confidence).toBe("low");+ expect(parsed.pinned).toBe(false);+ expect(parsed.scope).toBe("writing");+ });++ test("parses a confirmed preference with counters and last_evidence_at", () => {+ const res = writePreference(+ tmp,+ basePrefInput({+ status: "confirmed",+ confirmed_at: "2026-05-15T14:22:00Z",+ applied_count: 4,+ violated_count: 1,+ last_evidence_at: "2026-05-20T09:10:00Z",+ confidence: "medium",+ }),+ );+ const parsed = parsePreference(res.path);+ expect(parsed.status).toBe("confirmed");+ expect(parsed.confirmed_at).toBe("2026-05-15T14:22:00Z");+ expect(parsed.applied_count).toBe(4);+ expect(parsed.violated_count).toBe(1);+ expect(parsed.last_evidence_at).toBe("2026-05-20T09:10:00Z");+ expect(parsed.confidence).toBe("medium");+ });++ test("defaults `pinned` to false when the frontmatter omits the field entirely", () => {+ // Hand-write a frontmatter without the `pinned` line.+ const dirs = brainDirs(tmp);+ mkdirSync(dirs.preferences, { recursive: true });+ const path = preferencePath(tmp, "no-pin-field");+ const content = [+ "---",+ "kind: brain-preference",+ "id: pref-no-pin-field",+ "created_at: 2026-05-14T10:42:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference, brain/topic/no-pin-field]",+ "topic: no-pin-field",+ "status: unconfirmed",+ "principle: Some rule",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "---",+ "",+ "## Principle",+ "",+ "Some rule",+ "",+ ].join("\n");+ writeFileSync(path, content, "utf8");++ const parsed = parsePreference(path);+ expect(parsed.pinned).toBe(false);+ });++ test("respects pinned: true when explicitly set", () => {+ const res = writePreference(tmp, basePrefInput({ pinned: true }));+ const parsed = parsePreference(res.path);+ expect(parsed.pinned).toBe(true);+ });+});++describe("moveToRetired", () => {+ test("creates a retired file, removes the preference, and stamps retire metadata", () => {+ const written = writePreference(tmp, basePrefInput());+ expect(existsSync(written.path)).toBe(true);++ const now = new Date("2026-08-12T05:00:00Z");+ const result = moveToRetired(tmp, written.path, "stale-no-evidence", {+ now,+ retired_by: "[[Brain/log/2026-08-12]]",+ });++ expect(result.id).toBe("ret-no-internal-abbrev");+ expect(result.path).toBe(retiredPath(tmp, "no-internal-abbrev"));+ expect(existsSync(result.path)).toBe(true);+ expect(existsSync(written.path)).toBe(false);++ const parsed = parseRetired(result.path);+ expect(parsed.kind).toBe("brain-retired");+ expect(parsed.id).toBe("ret-no-internal-abbrev");+ expect(parsed.status).toBe("retired");+ expect(parsed.retired_at).toBe("2026-08-12T05:00:00.000Z");+ expect(parsed.retired_reason).toBe("stale-no-evidence");+ expect(parsed.retired_by).toBe("[[Brain/log/2026-08-12]]");+ // Inherited fields preserved.+ expect(parsed.topic).toBe("no-internal-abbrev");+ expect(parsed.principle).toContain("internal abbreviations");+ expect(parsed.evidenced_by).toEqual([+ "[[sig-2026-05-13-no-internal-abbrev]]",+ "[[sig-2026-05-14-no-internal-abbrev]]",+ ]);+ // The tag set rotates `brain/preference` β `brain/retired`.+ expect(parsed.tags).toContain("brain/retired");+ expect(parsed.tags).not.toContain("brain/preference");+ });++ test("optional superseded_by is captured in the retired frontmatter", () => {+ const written = writePreference(tmp, basePrefInput());+ const now = new Date("2026-08-12T05:00:00Z");+ const result = moveToRetired(tmp, written.path, "rebutted", {+ now,+ retired_by: "[[Brain/log/2026-08-12]]",+ superseded_by: "[[pref-newer-rule]]",+ });+ const parsed = parseRetired(result.path);+ expect(parsed.superseded_by).toBe("[[pref-newer-rule]]");+ });++ test("adds the prior pref-<slug> id as an alias so historical [[pref-X]] wikilinks resolve", () => {+ const written = writePreference(tmp, basePrefInput());+ const now = new Date("2026-08-12T05:00:00Z");+ const result = moveToRetired(tmp, written.path, "stale-no-evidence", {+ now,+ retired_by: "[[Brain/log/2026-08-12]]",+ });+ const parsed = parseRetired(result.path);+ expect(parsed.aliases).toBeDefined();+ expect(parsed.aliases).toContain("pref-no-internal-abbrev");+ });++ test("preserves any pre-existing aliases when adding the pref-<slug> alias on retire", () => {+ const written = writePreference(tmp, {+ ...basePrefInput(),+ aliases: ["my-friendly-name", "abbrev-rule"],+ });+ const now = new Date("2026-08-12T05:00:00Z");+ const result = moveToRetired(tmp, written.path, "stale-no-evidence", {+ now,+ retired_by: "[[Brain/log/2026-08-12]]",+ });+ const parsed = parseRetired(result.path);+ expect(parsed.aliases).toEqual([+ "pref-no-internal-abbrev",+ "my-friendly-name",+ "abbrev-rule",+ ]);+ });+});++describe("status-vs-folder mismatch", () => {+ test("file in preferences/ with status=retired triggers BrainStatusFolderMismatchError", () => {+ // Write a hand-crafted file directly to `preferences/` with the+ // wrong status β simulates a half-completed move.+ const dirs = brainDirs(tmp);+ mkdirSync(dirs.preferences, { recursive: true });+ const path = preferencePath(tmp, "broken");+ const content = [+ "---",+ "kind: brain-preference",+ "id: pref-broken",+ "created_at: 2026-05-14T10:42:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "status: retired",+ "principle: Hand-crafted mismatch",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ "## Principle",+ "",+ "Mismatch",+ "",+ ].join("\n");+ writeFileSync(path, content, "utf8");++ expect(() => parsePreference(path)).toThrow(BrainStatusFolderMismatchError);+ try {+ parsePreference(path);+ } catch (err) {+ expect(err).toBeInstanceOf(BrainStatusFolderMismatchError);+ const e = err as BrainStatusFolderMismatchError;+ expect(e.path).toBe(path);+ expect(e.status).toBe("retired");+ expect(e.folder).toBe("preferences");+ }+ });++ test("file in retired/ with kind=brain-preference (not brain-retired) is rejected by parseRetired", () => {+ // parseRetired requires kind=brain-retired; a stale `pref-` file+ // hand-moved into retired/ should fail early.+ const dirs = brainDirs(tmp);+ mkdirSync(dirs.retired, { recursive: true });+ const path = retiredPath(tmp, "broken");+ const content = [+ "---",+ "kind: brain-preference",+ "id: pref-broken",+ "created_at: 2026-05-14T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: broken",+ "status: retired",+ "principle: Hand-crafted mismatch",+ "---",+ "",+ ].join("\n");+ writeFileSync(path, content, "utf8");++ expect(() => parseRetired(path)).toThrow(/kind must be 'brain-retired'/);+ });+});++describe("status enum validation", () => {+ test("parsePreference rejects an unknown status value", () => {+ // A typo / hand-edit should never coerce into BrainPreferenceStatus+ // (`unconfirmed | confirmed`). "retired" remains tolerated because+ // it triggers the dedicated status-folder-mismatch error path.+ const dirs = brainDirs(tmp);+ mkdirSync(dirs.preferences, { recursive: true });+ const path = preferencePath(tmp, "invalid-status");+ const content = [+ "---",+ "kind: brain-preference",+ "id: pref-invalid-status",+ "created_at: 2026-05-14T10:42:00Z",+ "confirmed_at: null",+ "unconfirmed_until: 2026-05-28T10:42:00Z",+ "tags: [brain, brain/preference]",+ "topic: invalid-status",+ "status: hilarious",+ "principle: Hand-crafted invalid status",+ "evidenced_by: []",+ "applied_count: 0",+ "violated_count: 0",+ "last_evidence_at: null",+ "confidence: low",+ "pinned: false",+ "---",+ "",+ "## Principle",+ "",+ "Invalid",+ "",+ ].join("\n");+ writeFileSync(path, content, "utf8");++ expect(() => parsePreference(path)).toThrow(+ /preference status must be one of/,+ );+ });+});diff --git a/tests/core/brain.query.test.ts b/tests/core/brain.query.test.tsnew file mode 100644index 00000000..129a2527--- /dev/null+++ b/tests/core/brain.query.test.ts@@ -0,0 +1,317 @@+/**+ * Tests for src/core/brain/query.ts.+ *+ * The query helpers are read-only aggregators over Brain state. We+ * exercise them against a hand-built vault that combines:+ * - signals in inbox/ and inbox/processed/+ * - one active preference + one retired preference (same topic)+ * - log entries (`apply-evidence`, `promote`, `retire`)+ *+ * Each test creates a fresh tmpdir so cleanup is hermetic.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { brainDirs } from "../../src/core/brain/paths.ts";+import { appendLogEvent } from "../../src/core/brain/log.ts";+import {+ moveToRetired,+ writePreference,+} from "../../src/core/brain/preference.ts";+import { writeSignal } from "../../src/core/brain/signal.ts";+import {+ BrainNotFoundError,+ queryByLogSince,+ queryByPreference,+ queryByTopic,+} from "../../src/core/brain/query.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-query-"));+ // Pre-create the directory tree so writeSignal et al. find their+ // targets. brainDirs() returns absolute paths under <tmp>/Brain/.+ const dirs = brainDirs(tmp);+ for (const d of [+ dirs.brain,+ dirs.inbox,+ dirs.processed,+ dirs.preferences,+ dirs.retired,+ dirs.log,+ ]) {+ mkdirSync(d, { recursive: true });+ }+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function basePref(slug: string) {+ return {+ slug,+ topic: slug,+ principle: `Principle for ${slug}`,+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed" as const,+ evidenced_by: [+ `[[sig-2026-05-13-${slug}]]`,+ `[[sig-2026-05-14-${slug}]]`,+ ],+ scope: "writing",+ confirmed_at: null,+ };+}++describe("queryByPreference", () => {+ test("returns the preference and its applied-evidence trail in chronological order", () => {+ writePreference(tmp, basePref("alpha"));+ // Three apply-evidence entries on different days; the function+ // sorts by timestamp ascending regardless of write order.+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T18:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-alpha]]",+ artifact: "[[Daily/2026.05.14]]",+ agent: "claude",+ result: "applied",+ },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T12:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-alpha]]",+ artifact: "[[Daily/2026.05.14-early]]",+ agent: "claude",+ result: "applied",+ },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-15T08:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-alpha]]",+ artifact: "[[Daily/2026.05.15]]",+ agent: "codex",+ result: "violated",+ },+ });++ const res = queryByPreference(tmp, "pref-alpha");+ expect(res.preference.id).toBe("pref-alpha");+ expect(res.evidence).toHaveLength(3);+ expect(res.evidence.map((e) => e.timestamp)).toEqual([+ "2026-05-14T12:00:00Z",+ "2026-05-14T18:00:00Z",+ "2026-05-15T08:00:00Z",+ ]);+ });++ test("retired preferences are reachable by their `pref-` id (fallback) and by `ret-` id", () => {+ const written = writePreference(tmp, basePref("beta"));+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T10:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-beta]]",+ artifact: "[[Daily/2026.05.14]]",+ agent: "claude",+ result: "applied",+ },+ });+ moveToRetired(tmp, written.path, "stale-no-evidence", {+ now: new Date("2026-08-12T05:00:00Z"),+ retired_by: "[[Brain/log/2026-08-12]]",+ });++ // Pref-id fallback to ret-: returns the retired entry.+ const viaPref = queryByPreference(tmp, "pref-beta");+ expect(viaPref.preference.id).toBe("ret-beta");+ expect("retired_at" in viaPref.preference).toBe(true);+ expect(viaPref.evidence).toHaveLength(1);++ // Direct ret-id lookup also resolves.+ const viaRet = queryByPreference(tmp, "ret-beta");+ expect(viaRet.preference.id).toBe("ret-beta");+ expect(viaRet.evidence).toHaveLength(1);+ });++ test("throws BrainNotFoundError when no preference matches", () => {+ expect(() => queryByPreference(tmp, "pref-nonexistent")).toThrow(+ BrainNotFoundError,+ );+ expect(() => queryByPreference(tmp, "garbage")).toThrow(+ BrainNotFoundError,+ );+ expect(() => queryByPreference(tmp, "")).toThrow(BrainNotFoundError);+ });++ test("rejects path-traversal style ids before forming a filesystem path", () => {+ // Without slug-shape validation, `pref-../../etc/passwd` would form+ // `<dirs.preferences>/pref-../../etc/passwd.md` and `existsSync`+ // could resolve outside the vault on a permissive filesystem. We+ // surface this as `BrainNotFoundError` so the caller sees the same+ // shape as any other unknown id.+ expect(() => queryByPreference(tmp, "pref-../escape")).toThrow(+ BrainNotFoundError,+ );+ expect(() => queryByPreference(tmp, "pref-..")).toThrow(BrainNotFoundError);+ expect(() => queryByPreference(tmp, "pref-with/slash")).toThrow(+ BrainNotFoundError,+ );+ expect(() => queryByPreference(tmp, "ret-../escape")).toThrow(+ BrainNotFoundError,+ );+ });++ test("preference without any applied evidence still resolves with empty `evidence` array", () => {+ writePreference(tmp, basePref("gamma"));+ const res = queryByPreference(tmp, "pref-gamma");+ expect(res.preference.id).toBe("pref-gamma");+ expect(res.evidence).toEqual([]);+ });+});++describe("queryByTopic", () => {+ test("collects active and processed signals plus the active preference", () => {+ // Two signals β one active, one already processed.+ writeSignal(tmp, {+ topic: "no-internal-abbrev",+ signal: "negative",+ agent: "claude",+ principle: "expand abbreviations",+ created_at: "2026-05-13T10:00:00Z",+ date: "2026-05-13",+ slug: "no-internal-abbrev",+ });+ // Write a "processed" signal directly under inbox/processed/.+ const dirs = brainDirs(tmp);+ writeSignal(tmp, {+ topic: "no-internal-abbrev",+ signal: "negative",+ agent: "claude",+ principle: "expand abbreviations",+ created_at: "2026-05-14T10:00:00Z",+ date: "2026-05-14",+ slug: "no-internal-abbrev",+ });+ // Move the second one to processed/ to simulate dream's effect.+ const { renameSync } = require("node:fs") as typeof import("node:fs");+ renameSync(+ join(dirs.inbox, "sig-2026-05-14-no-internal-abbrev.md"),+ join(dirs.processed, "sig-2026-05-14-no-internal-abbrev.md"),+ );++ writePreference(tmp, basePref("no-internal-abbrev"));+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T11:00:00Z",+ eventType: "promote",+ body: { preference: "[[pref-no-internal-abbrev]]" },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T15:00:00Z",+ eventType: "apply-evidence",+ body: {+ preference: "[[pref-no-internal-abbrev]]",+ artifact: "[[Daily/2026.05.14]]",+ agent: "claude",+ result: "applied",+ },+ });++ const res = queryByTopic(tmp, "no-internal-abbrev");+ expect(res.signals).toHaveLength(2);+ expect(res.signals.map((s) => s.id)).toEqual([+ "sig-2026-05-13-no-internal-abbrev",+ "sig-2026-05-14-no-internal-abbrev",+ ]);+ expect(res.preference?.id).toBe("pref-no-internal-abbrev");+ expect(res.all_log_events).toHaveLength(2);+ expect(res.all_log_events.map((e) => e.eventType)).toEqual([+ "promote",+ "apply-evidence",+ ]);+ });++ test("falls back to retired preference when no active one exists for the topic", () => {+ const written = writePreference(tmp, basePref("orphan"));+ moveToRetired(tmp, written.path, "rebutted", {+ now: new Date("2026-08-12T05:00:00Z"),+ retired_by: "[[Brain/log/2026-08-12]]",+ });+ const res = queryByTopic(tmp, "orphan");+ expect(res.preference?.id).toBe("ret-orphan");+ expect(res.signals).toEqual([]);+ });++ test("multiple preferences with the same topic resolve deterministically (sorted by filename)", () => {+ // Two active preferences sharing the same topic β pathological but+ // not impossible (e.g. mid-rename, conflict-merge). The query must+ // return the same one every call regardless of readdir order, so+ // tooling that pins on the result stays stable. We pick the+ // lexicographically-smallest filename as the canonical winner.+ writePreference(tmp, { ...basePref("zebra"), slug: "zebra", topic: "shared-topic" });+ writePreference(tmp, { ...basePref("alpha"), slug: "alpha", topic: "shared-topic" });+ writePreference(tmp, { ...basePref("middle"), slug: "middle", topic: "shared-topic" });++ const r1 = queryByTopic(tmp, "shared-topic");+ const r2 = queryByTopic(tmp, "shared-topic");+ const r3 = queryByTopic(tmp, "shared-topic");+ expect(r1.preference?.id).toBe("pref-alpha");+ expect(r2.preference?.id).toBe("pref-alpha");+ expect(r3.preference?.id).toBe("pref-alpha");+ });++ test("unknown topic returns null preference and empty signals/events", () => {+ const res = queryByTopic(tmp, "never-existed");+ expect(res.signals).toEqual([]);+ expect(res.preference).toBeNull();+ expect(res.all_log_events).toEqual([]);+ });+});++describe("queryByLogSince", () => {+ test("returns log entries at or after `since`, in chronological order", () => {+ appendLogEvent(tmp, {+ timestamp: "2026-05-12T10:00:00Z",+ eventType: "feedback",+ body: { signal: "[[sig-a]]" },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-14T14:00:00Z",+ eventType: "feedback",+ body: { signal: "[[sig-b]]" },+ });+ appendLogEvent(tmp, {+ timestamp: "2026-05-13T18:00:00Z",+ eventType: "feedback",+ body: { signal: "[[sig-c]]" },+ });++ const res = queryByLogSince(tmp, new Date("2026-05-13T00:00:00Z"));+ expect(res).toHaveLength(2);+ expect(res.map((e) => e.timestamp)).toEqual([+ "2026-05-13T18:00:00Z",+ "2026-05-14T14:00:00Z",+ ]);+ });++ test("invalid Date throws TypeError", () => {+ expect(() =>+ queryByLogSince(tmp, new Date("totally-not-a-date")),+ ).toThrow(TypeError);+ });++ test("empty log returns empty array (no throw)", () => {+ const res = queryByLogSince(tmp, new Date("2026-05-13T00:00:00Z"));+ expect(res).toEqual([]);+ });+});diff --git a/tests/core/brain.signal.test.ts b/tests/core/brain.signal.test.tsnew file mode 100644index 00000000..7fbb3cb2--- /dev/null+++ b/tests/core/brain.signal.test.ts@@ -0,0 +1,210 @@+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 {+ parseSignal,+ writeSignal,+ type WriteSignalInput,+} from "../../src/core/brain/signal.ts";++let tmp: string;++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-signal-"));+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+});++function baseInput(overrides: Partial<WriteSignalInput> = {}): WriteSignalInput {+ return {+ topic: "no-internal-abbrev",+ signal: "negative",+ agent: "claude",+ principle: "Do not use internal abbreviations in user-facing copy unless explained first",+ created_at: "2026-05-14T10:15:00Z",+ date: "2026-05-14",+ slug: "no-internal-abbrev",+ scope: "writing",+ source: ["[[Daily/2026.05.14]]", "[[blog-header-draft]]"],+ raw: "Sergey pointed out that OSB appeared as an abbreviation.",+ ...overrides,+ };+}++describe("writeSignal β required field validation", () => {+ // Test each required field independently. The contract is+ // `Error('signal missing field: <name>')` so a regression that+ // changes the message format would be caught here.+ const requiredFields: ReadonlyArray<keyof WriteSignalInput> = [+ "topic",+ "signal",+ "agent",+ "principle",+ "created_at",+ "date",+ "slug",+ ];+ for (const field of requiredFields) {+ test(`missing '${String(field)}' throws naming the field`, () => {+ const input = baseInput();+ // `as any`-equivalent without `any`: structurally remove the+ // field by composing a fresh object that omits it.+ const partial = { ...input } as Record<string, unknown>;+ delete partial[field as string];+ expect(() =>+ writeSignal(tmp, partial as unknown as WriteSignalInput),+ ).toThrow(new RegExp(`signal missing field: ${String(field)}`));+ });+ }++ test("invalid signal value throws", () => {+ expect(() =>+ writeSignal(tmp, baseInput({ signal: "neutral" as unknown as "positive" })),+ ).toThrow(/must be 'positive' or 'negative'/);+ });+});++describe("writeSignal + parseSignal roundtrip", () => {+ test("parses every field that was written", () => {+ const result = writeSignal(tmp, baseInput());+ expect(result.id).toBe("sig-2026-05-14-no-internal-abbrev");+ const parsed = parseSignal(result.path);+ expect(parsed.kind).toBe("brain-signal");+ expect(parsed.id).toBe(result.id);+ expect(parsed.created_at).toBe("2026-05-14T10:15:00Z");+ expect(parsed.topic).toBe("no-internal-abbrev");+ expect(parsed.signal).toBe("negative");+ expect(parsed.agent).toBe("claude");+ expect(parsed.scope).toBe("writing");+ expect(parsed.principle).toContain("internal abbreviations");+ expect(parsed.tags).toContain("brain");+ expect(parsed.tags).toContain("brain/signal");+ expect(parsed.tags).toContain("brain/topic/no-internal-abbrev");+ expect(parsed.tags).toContain("brain/scope/writing");+ expect(parsed.source).toEqual([+ "[[Daily/2026.05.14]]",+ "[[blog-header-draft]]",+ ]);+ expect(parsed.raw).toContain("Sergey pointed out");+ });++ test("byte-equal roundtrip: write β parse β write to a fresh slug β identical bytes", () => {+ // Step 1: original write.+ const first = writeSignal(tmp, baseInput());+ const firstBytes = readFileSync(first.path, "utf8");++ // Step 2: parse what we wrote.+ const parsed = parseSignal(first.path);++ // Step 3: write to a second slug; same input, different filename+ // (so we can compare bytes without colliding on the first file).+ const second = writeSignal(+ tmp,+ baseInput({+ slug: "no-internal-abbrev-roundtrip",+ }),+ );+ const secondBytes = readFileSync(second.path, "utf8");++ // The two files differ only on the `id:` line and the filename+ // baked into the id; everything else must be byte-identical.+ const normalize = (s: string): string =>+ s+ .replace(/^id:.*$/m, "id: <ID>")+ .replace(/\bno-internal-abbrev-roundtrip\b/g, "no-internal-abbrev");+ expect(normalize(firstBytes)).toBe(normalize(secondBytes));++ // And the parsed source array survives untouched.+ expect(parsed.source).toEqual([+ "[[Daily/2026.05.14]]",+ "[[blog-header-draft]]",+ ]);+ });+});++describe("writeSignal β wikilink preservation", () => {+ test("wikilink strings in source[] survive parse β write β parse unchanged", () => {+ const input = baseInput({+ source: ["[[Daily/2026.05.14]]", "[[blog-header-draft]]"],+ });+ const first = writeSignal(tmp, input);+ const parsed = parseSignal(first.path);+ expect(parsed.source).toEqual([+ "[[Daily/2026.05.14]]",+ "[[blog-header-draft]]",+ ]);++ // Write again to a different slug, then re-parse.+ const second = writeSignal(tmp, {+ ...input,+ slug: "wiki-roundtrip",+ source: [...parsed.source!],+ });+ const reparsed = parseSignal(second.path);+ expect(reparsed.source).toEqual([+ "[[Daily/2026.05.14]]",+ "[[blog-header-draft]]",+ ]);+ });++ test("file body actually contains the wikilink literally", () => {+ const result = writeSignal(tmp, baseInput());+ const bytes = readFileSync(result.path, "utf8");+ expect(bytes).toContain("[[Daily/2026.05.14]]");+ expect(bytes).toContain("[[blog-header-draft]]");+ });+});++describe("extractRawSection (via parseSignal)", () => {+ test("multi-line raw block survives the roundtrip in full (regression on m-flag $)", () => {+ // With the regex `/^##\s+Raw\s*\n+([\s\S]*?)\s*$/m`, the `m` flag+ // makes `$` match end-of-line β the lazy `[\s\S]*?` capture was+ // truncated at the first newline. The fix drops the `m` flag so+ // `$` only matches end-of-string, letting the full multi-line raw+ // block flow into the capture group.+ const multiLine = [+ "First line of the raw quote.",+ "Second line continues the thought.",+ "",+ "Third line after a blank gap.",+ ].join("\n");+ const result = writeSignal(tmp, baseInput({+ slug: "multi-line-raw",+ raw: multiLine,+ }));+ const parsed = parseSignal(result.path);+ expect(parsed.raw).toBe(multiLine);+ });++ test("missing or placeholder raw returns undefined", () => {+ // The "## Raw\n\n_(not provided)_" placeholder should always parse+ // back to `undefined` so the schema shape stays clean.+ const noRawInput = baseInput({ slug: "no-raw" });+ delete (noRawInput as { raw?: string }).raw;+ const result = writeSignal(tmp, noRawInput);+ const parsed = parseSignal(result.path);+ expect(parsed.raw).toBeUndefined();+ });+});++describe("writeSignal β slug collision allocator", () => {+ test("second write with the same slug receives a `-2` suffix", () => {+ const a = writeSignal(tmp, baseInput());+ expect(a.id).toBe("sig-2026-05-14-no-internal-abbrev");++ const b = writeSignal(tmp, baseInput());+ expect(b.id).toBe("sig-2026-05-14-no-internal-abbrev-2");+ expect(b.path).not.toBe(a.path);+ });++ test("third write with the same slug receives `-3`", () => {+ writeSignal(tmp, baseInput());+ writeSignal(tmp, baseInput());+ const c = writeSignal(tmp, baseInput());+ expect(c.id).toBe("sig-2026-05-14-no-internal-abbrev-3");+ });+});diff --git a/tests/core/brain.snapshot.test.ts b/tests/core/brain.snapshot.test.tsnew file mode 100644index 00000000..d2313d1b--- /dev/null+++ b/tests/core/brain.snapshot.test.ts@@ -0,0 +1,232 @@+import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ utimesSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ BrainSnapshotToolingMissingError,+ createSnapshot,+ listSnapshots,+ pruneSnapshots,+ restoreSnapshot,+} from "../../src/core/brain/snapshot.ts";+import { brainDirs, snapshotPath } from "../../src/core/brain/paths.ts";+import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";++let vault: string;+let configHome: string;+let configPath: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-snap-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-snap-cfg-"));+ configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });++ // Seed a minimal but interesting Brain/ tree.+ const dirs = brainDirs(vault);+ writeFileSync(+ join(dirs.inbox, "sig-2026-05-14-foo.md"),+ "---\nkind: brain-signal\n---\n\n## Raw\n\nseed\n",+ );+ writeFileSync(+ join(dirs.preferences, "pref-foo.md"),+ "---\nkind: brain-preference\n---\n\n## Principle\n\nseed\n",+ );+ writeFileSync(+ join(dirs.log, "2026-05-14.md"),+ "---\nkind: brain-log\n---\n\n# Brain log β 2026-05-14\n",+ );+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++describe("createSnapshot", () => {+ test("captures every top-level Brain/ entry except .snapshots/", () => {+ const dirs = brainDirs(vault);+ // Place a sentinel inside .snapshots/ to confirm it is NOT bundled+ // into the new archive.+ writeFileSync(join(dirs.snapshots, "sentinel.tar.zst"), "X");++ const res = createSnapshot(vault, "dream-2026-05-14-070000");+ expect(existsSync(res.path)).toBe(true);++ // Extract into a fresh tmp and inspect.+ const tmp = mkdtempSync(join(tmpdir(), "o2b-snap-verify-"));+ try {+ // Use system tar+zstd for verification (mirror what restore does+ // but in-test).+ const { spawnSync } = require("node:child_process") as typeof import("node:child_process");+ const zstd = spawnSync("zstd", ["-d", "-c", res.path], {+ stdio: ["ignore", "pipe", "pipe"],+ maxBuffer: 64 * 1024 * 1024,+ });+ expect(zstd.status).toBe(0);+ const tar = spawnSync("tar", ["-x", "-C", tmp], {+ input: zstd.stdout,+ stdio: ["pipe", "inherit", "pipe"],+ });+ expect(tar.status).toBe(0);++ const extracted = join(tmp, "Brain");+ expect(existsSync(extracted)).toBe(true);+ expect(existsSync(join(extracted, "_brain.yaml"))).toBe(true);+ expect(existsSync(join(extracted, "_BRAIN.md"))).toBe(true);+ expect(+ existsSync(join(extracted, "inbox", "sig-2026-05-14-foo.md")),+ ).toBe(true);+ expect(existsSync(join(extracted, "preferences", "pref-foo.md"))).toBe(true);+ // The .snapshots/ directory MUST NOT be inside the archive.+ expect(existsSync(join(extracted, ".snapshots"))).toBe(false);+ } finally {+ rmSync(tmp, { recursive: true, force: true });+ }+ });++ test("rejects invalid run_id", () => {+ expect(() => createSnapshot(vault, "../escape")).toThrow();+ });+});++describe("listSnapshots", () => {+ test("returns archives in newest-first order by mtime", () => {+ createSnapshot(vault, "dream-2026-05-14-070000");+ // Force an older mtime on the first archive so the ordering is+ // unambiguous regardless of how fast the test runs.+ const a = snapshotPath(vault, "dream-2026-05-14-070000");+ const oldT = new Date("2026-05-13T00:00:00Z");+ utimesSync(a, oldT, oldT);++ createSnapshot(vault, "dream-2026-05-14-080000");+ const b = snapshotPath(vault, "dream-2026-05-14-080000");+ const midT = new Date("2026-05-14T00:00:00Z");+ utimesSync(b, midT, midT);++ createSnapshot(vault, "dream-2026-05-14-090000");+ const c = snapshotPath(vault, "dream-2026-05-14-090000");+ const newT = new Date("2026-05-15T00:00:00Z");+ utimesSync(c, newT, newT);++ const list = listSnapshots(vault);+ expect(list).toHaveLength(3);+ expect(list[0]!.run_id).toBe("dream-2026-05-14-090000");+ expect(list[1]!.run_id).toBe("dream-2026-05-14-080000");+ expect(list[2]!.run_id).toBe("dream-2026-05-14-070000");+ for (const s of list) {+ expect(s.size_bytes).toBeGreaterThan(0);+ expect(s.path.endsWith(".tar.zst")).toBe(true);+ }+ });++ test("returns [] when .snapshots/ is empty", () => {+ expect(listSnapshots(vault)).toEqual([]);+ });+});++describe("pruneSnapshots", () => {+ test("removes oldest archives, keeps the retention_count newest", () => {+ const labels = ["a", "b", "c", "d", "e"];+ const ts = [+ "2026-05-10T00:00:00Z",+ "2026-05-11T00:00:00Z",+ "2026-05-12T00:00:00Z",+ "2026-05-13T00:00:00Z",+ "2026-05-14T00:00:00Z",+ ];+ for (let i = 0; i < labels.length; i++) {+ const runId = `dream-${labels[i]}-000000`;+ createSnapshot(vault, runId);+ const p = snapshotPath(vault, runId);+ const t = new Date(ts[i]!);+ utimesSync(p, t, t);+ }+ const before = listSnapshots(vault);+ expect(before).toHaveLength(5);++ const res = pruneSnapshots(vault, 3);+ expect(res.deleted).toHaveLength(2);++ const after = listSnapshots(vault);+ expect(after).toHaveLength(3);+ expect(after.map((s) => s.run_id)).toEqual([+ "dream-e-000000",+ "dream-d-000000",+ "dream-c-000000",+ ]);+ });++ test("noop when fewer files than retention_count", () => {+ createSnapshot(vault, "dream-only");+ const res = pruneSnapshots(vault, 10);+ expect(res.deleted).toEqual([]);+ expect(listSnapshots(vault)).toHaveLength(1);+ });+});++describe("restoreSnapshot β round-trip integrity", () => {+ test("state A β snapshot β mutate to B β restore A β bytes match for key files (excluding .snapshots/)", () => {+ const dirs = brainDirs(vault);+ const prefPath = join(dirs.preferences, "pref-foo.md");+ const sigPath = join(dirs.inbox, "sig-2026-05-14-foo.md");+ // Capture state A.+ const stateAPref = readFileSync(prefPath, "utf8");+ const stateASig = readFileSync(sigPath, "utf8");++ const snap = createSnapshot(vault, "dream-stateA");+ expect(existsSync(snap.path)).toBe(true);++ // Mutate to state B: rewrite a pref, delete a signal, add a new+ // file. Also put a *new* snapshot under .snapshots/ that should+ // survive the restore (this is the load-bearing invariant).+ writeFileSync(prefPath, "MUTATED PREF CONTENT");+ rmSync(sigPath);+ writeFileSync(join(dirs.inbox, "sig-newer.md"), "newer-content");+ // Create another snapshot β restoring stateA must NOT erase it.+ const newer = createSnapshot(vault, "dream-stateB");+ expect(existsSync(newer.path)).toBe(true);++ const res = restoreSnapshot(vault, "dream-stateA");+ expect(res.restored_files).toBeGreaterThan(0);++ // Key files restored byte-equal.+ expect(readFileSync(prefPath, "utf8")).toBe(stateAPref);+ expect(readFileSync(sigPath, "utf8")).toBe(stateASig);+ // The post-stateA new file should be gone.+ expect(existsSync(join(dirs.inbox, "sig-newer.md"))).toBe(false);+ // BOTH snapshots must survive β including the one made AFTER the+ // restored state, so the operator still has a forward path.+ expect(existsSync(snap.path)).toBe(true);+ expect(existsSync(newer.path)).toBe(true);+ });+});++describe("snapshot tooling absent", () => {+ test("createSnapshot throws BrainSnapshotToolingMissingError when tar absent", () => {+ // Synthetic vault root that bootstraps fine; then we run with a+ // sanitized PATH so neither tar nor compressors are available.+ const dirs = brainDirs(vault);+ mkdirSync(dirs.snapshots, { recursive: true });+ const originalPath = process.env["PATH"];+ process.env["PATH"] = "/nonexistent-path-for-test";+ try {+ expect(() => createSnapshot(vault, "dream-no-tools")).toThrow(+ BrainSnapshotToolingMissingError,+ );+ } finally {+ process.env["PATH"] = originalPath;+ }+ });+});diff --git a/tests/core/brain.types.test.ts b/tests/core/brain.types.test.tsnew file mode 100644index 00000000..cc1a790b--- /dev/null+++ b/tests/core/brain.types.test.ts@@ -0,0 +1,182 @@+import { describe, expect, test } from "bun:test";++import {+ BRAIN_APPLY_RESULT,+ BRAIN_CONFIDENCE,+ BRAIN_LOG_EVENT_KIND,+ BRAIN_PREFERENCE_STATUS,+ BRAIN_RETIRED_REASON,+ BRAIN_SIGNAL_SIGN,+} from "../../src/core/brain/types.ts";+import type {+ BrainApplyEvidenceLogEvent,+ BrainConfig,+ BrainPreference,+ BrainRetired,+ BrainSignal,+} from "../../src/core/brain/types.ts";++// These tests are a type-checking smoke screen. The `satisfies` operator+// pins each literal to its interface; a regression in the type shape+// would surface as a compile-time error (caught by `bun run typecheck`),+// while the runtime assertions below cover the const enums.++describe("BRAIN_* const enums", () => {+ test("BRAIN_SIGNAL_SIGN values", () => {+ expect(BRAIN_SIGNAL_SIGN.positive).toBe("positive");+ expect(BRAIN_SIGNAL_SIGN.negative).toBe("negative");+ });++ test("BRAIN_PREFERENCE_STATUS values", () => {+ expect(BRAIN_PREFERENCE_STATUS.unconfirmed).toBe("unconfirmed");+ expect(BRAIN_PREFERENCE_STATUS.confirmed).toBe("confirmed");+ });++ test("BRAIN_CONFIDENCE values", () => {+ expect(BRAIN_CONFIDENCE.low).toBe("low");+ expect(BRAIN_CONFIDENCE.medium).toBe("medium");+ expect(BRAIN_CONFIDENCE.high).toBe("high");+ });++ test("BRAIN_RETIRED_REASON covers all four reasons from Β§7.4", () => {+ expect(BRAIN_RETIRED_REASON.staleNoEvidence).toBe("stale-no-evidence");+ expect(BRAIN_RETIRED_REASON.expiredUnconfirmed).toBe("expired-unconfirmed");+ expect(BRAIN_RETIRED_REASON.rebutted).toBe("rebutted");+ expect(BRAIN_RETIRED_REASON.userRejected).toBe("user-rejected");+ });++ test("BRAIN_APPLY_RESULT values", () => {+ expect(BRAIN_APPLY_RESULT.applied).toBe("applied");+ expect(BRAIN_APPLY_RESULT.violated).toBe("violated");+ });++ test("BRAIN_LOG_EVENT_KIND covers every event type listed in Β§5.5 / Β§7.4", () => {+ const expected = new Set<string>([+ "dream",+ "feedback",+ "apply-evidence",+ "force-confirmed",+ "reject",+ "promote",+ "retire",+ "noted-redundant",+ "skip-corrupted-frontmatter",+ "pin",+ "unpin",+ "rollback",+ ]);+ const actual = new Set<string>(Object.values(BRAIN_LOG_EVENT_KIND));+ expect(actual).toEqual(expected);+ });+});++describe("interface shape smoke (compile-time)", () => {+ test("BrainSignal literal satisfies the type", () => {+ const sig = {+ kind: "brain-signal",+ id: "sig-2026-05-14-no-internal-abbrev",+ created_at: "2026-05-14T10:15:00Z",+ tags: ["brain", "brain/signal", "brain/topic/no-internal-abbrev"],+ topic: "no-internal-abbrev",+ scope: "writing",+ signal: BRAIN_SIGNAL_SIGN.negative,+ agent: "claude",+ source: ["[[Daily/2026.05.14]]"],+ principle: "Do not use internal abbreviations",+ } as const satisfies BrainSignal;+ expect(sig.kind).toBe("brain-signal");+ expect(sig.signal).toBe("negative");+ });++ test("BrainPreference allows pinned=false default and confirmed state", () => {+ const unconfirmed = {+ kind: "brain-preference",+ id: "pref-no-internal-abbrev",+ created_at: "2026-05-14T10:42:00Z",+ confirmed_at: null,+ unconfirmed_until: "2026-05-28T10:42:00Z",+ tags: ["brain", "brain/preference"],+ topic: "no-internal-abbrev",+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,+ principle: "Do not use internal abbreviations",+ evidenced_by: ["[[sig-2026-05-13-no-internal-abbrev]]"],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: null,+ confidence: BRAIN_CONFIDENCE.low,+ pinned: false,+ } as const satisfies BrainPreference;+ expect(unconfirmed.confirmed_at).toBeNull();+ expect(unconfirmed.pinned).toBe(false);+ expect(unconfirmed.status).toBe("unconfirmed");++ const confirmed = {+ ...unconfirmed,+ confirmed_at: "2026-05-15T09:00:00Z",+ status: BRAIN_PREFERENCE_STATUS.confirmed,+ applied_count: 1,+ last_evidence_at: "2026-05-15T09:00:00Z",+ pinned: true,+ } as const satisfies BrainPreference;+ expect(confirmed.status).toBe("confirmed");+ expect(confirmed.pinned).toBe(true);+ });++ test("BrainRetired enforces status='retired' and a valid reason", () => {+ const retired = {+ kind: "brain-retired",+ id: "ret-no-internal-abbrev",+ status: "retired",+ retired_at: "2026-08-12T05:00:00Z",+ retired_reason: BRAIN_RETIRED_REASON.staleNoEvidence,+ retired_by: "[[Brain/log/2026-08-12]]",+ created_at: "2026-05-14T10:42:00Z",+ tags: ["brain", "brain/retired"],+ topic: "no-internal-abbrev",+ principle: "Do not use internal abbreviations",+ evidenced_by: ["[[sig-2026-05-14-no-internal-abbrev]]"],+ applied_count: 0,+ violated_count: 0,+ last_evidence_at: "2026-05-14T10:42:00Z",+ confidence: BRAIN_CONFIDENCE.low,+ pinned: false,+ } as const satisfies BrainRetired;+ expect(retired.status).toBe("retired");+ expect(retired.retired_reason).toBe("stale-no-evidence");+ });++ test("BrainApplyEvidenceLogEvent narrows on `kind`", () => {+ const ev = {+ kind: BRAIN_LOG_EVENT_KIND.applyEvidence,+ at: "2026-05-14T14:22:00Z",+ payload: { result: "applied" },+ preference: "pref-no-internal-abbrev",+ artifact: "[[Daily/2026.05.14#section-blog-post]]",+ agent: "claude",+ result: BRAIN_APPLY_RESULT.applied,+ note: "Expanded OSB on first use",+ } as const satisfies BrainApplyEvidenceLogEvent;+ expect(ev.kind).toBe("apply-evidence");+ expect(ev.result).toBe("applied");+ });++ test("BrainConfig with defaults compiles", () => {+ const cfg = {+ schema_version: 1,+ dream: {+ candidate_threshold: 3,+ unconfirmed_window_days: 14,+ contradiction_window_days: 14,+ },+ retire: { stale_evidence_days: 90 },+ confidence: {+ low_max_applied: 2,+ high_min_applied: 10,+ high_freshness_factor: 0.8,+ },+ snapshots: { retention_count: 10 },+ } as const satisfies BrainConfig;+ expect(cfg.schema_version).toBe(1);+ expect(cfg.snapshots.retention_count).toBe(10);+ });+});diff --git a/tests/hooks/post-write-reminder.test.ts b/tests/hooks/post-write-reminder.test.tsindex 147759b3..17e45a1d 100644--- a/tests/hooks/post-write-reminder.test.ts+++ b/tests/hooks/post-write-reminder.test.ts@@ -53,7 +53,9 @@ describe("post-write-reminder hook", () => {expect(out.hookSpecificOutput.hookEventName).toBe("PostToolUse");expect(out.hookSpecificOutput.additionalContext).toContain("`Write`");expect(out.hookSpecificOutput.additionalContext).toContain("/tmp/foo.md");- expect(out.hookSpecificOutput.additionalContext).toContain("event_log_append");+ expect(out.hookSpecificOutput.additionalContext).toContain("brain_feedback");+ expect(out.hookSpecificOutput.additionalContext).toContain("brain_apply_evidence");+ expect(out.hookSpecificOutput.additionalContext).not.toContain("event_log_append");});test("emits additionalContext for Codex apply_patch with patch body", async () => {diff --git a/tests/mcp/brain.test.ts b/tests/mcp/brain.test.tsnew file mode 100644index 00000000..3e7ace43--- /dev/null+++ b/tests/mcp/brain.test.ts@@ -0,0 +1,628 @@+/**+ * MCP integration tests for the six Brain tools.+ *+ * These exercise the full handler path (`MCPServer.handleRequest β+ * tools/call β handler β core/brain/*`). We rely on the existing+ * `MCPServer` plumbing β no direct handler imports β so a regression in+ * tool registration or argument coercion is caught here too.+ *+ * Each test stands up a fresh tmp vault, initialises the Brain layer+ * via `bootstrapBrain` (mirrors what `o2b brain init` would do), and+ * tears down at the end. Wall-clock-sensitive cases pin time via the+ * tool's own `now` argument.+ */++import {+ afterEach,+ beforeEach,+ describe,+ expect,+ test,+} from "bun:test";+import {+ existsSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import {+ JSONRPC_VERSION,+ MCPServer,+ PROTOCOL_VERSION,+} from "../../src/mcp/index.ts";+import { buildToolTable } from "../../src/mcp/tools.ts";+import { bootstrapBrain } from "../../src/core/brain/init.ts";+import {+ brainDirs,+ preferencePath,+} from "../../src/core/brain/paths.ts";+import { writeSignal } from "../../src/core/brain/signal.ts";+import { writePreference } from "../../src/core/brain/preference.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { vaultRelativeSafe } from "../../src/mcp/brain-tools.ts";++let tmp: string;+let vault: string;+let configHome: string;+let configPath: string;+const savedEnv: Record<string, string | undefined> = {};++beforeEach(() => {+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-"));+ vault = join(tmp, "vault");+ configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-cfg-"));+ configPath = join(configHome, "config.yaml");+ for (const k of [+ "VAULT_AGENT_NAME",+ "VAULT_TIMEZONE",+ "VAULT_DIR",+ "OPEN_SECOND_BRAIN_CONFIG",+ ]) {+ savedEnv[k] = process.env[k];+ delete process.env[k];+ }+ // Isolate from any system-wide plugin config β the project's own+ // dev config on the developer's machine would otherwise leak through.+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(tmp, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+ for (const [k, v] of Object.entries(savedEnv)) {+ if (v === undefined) delete process.env[k];+ else process.env[k] = v;+ }+});++async function initialize(server: MCPServer): Promise<void> {+ await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 1,+ method: "initialize",+ params: {+ protocolVersion: PROTOCOL_VERSION,+ capabilities: {},+ clientInfo: { name: "brain-test", version: "0" },+ },+ });+ await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ method: "notifications/initialized",+ });+}++async function call(+ server: MCPServer,+ name: string,+ args: Record<string, unknown> = {},+): Promise<any> {+ return server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 99,+ method: "tools/call",+ params: { name, arguments: args },+ });+}++function makeServer(): MCPServer {+ return new MCPServer({ vault, configPath });+}++// ---------------------------------------------------------------------------+// brain_feedback+// ---------------------------------------------------------------------------++describe("vaultRelativeSafe", () => {+ test("returns the original target unchanged when target is outside the vault", () => {+ // Cross-platform regression: the prior implementation used a+ // hard-coded `/` separator and a prefix-match. On Windows it would+ // misbehave for `C:\Users\...`-style absolute paths. Using+ // `path.relative` / `path.isAbsolute` is the correct shape.+ const outOfVault = "/tmp/somewhere-else/file.md";+ expect(vaultRelativeSafe(vault, outOfVault)).toBe(outOfVault);+ });++ test("returns vault-relative path for an in-vault target", () => {+ const inVault = join(vault, "Brain", "inbox", "sig-x.md");+ const rel = vaultRelativeSafe(vault, inVault);+ expect(rel).toBe(join("Brain", "inbox", "sig-x.md"));+ // The returned path must NOT be absolute β that's the property+ // every downstream consumer (digest, JSON output) relies on.+ expect(rel.startsWith("/")).toBe(false);+ });++ test("returns empty string when target equals the vault root", () => {+ expect(vaultRelativeSafe(vault, vault)).toBe("");+ });+});++describe("brain_feedback tool schema", () => {+ test("force_confirmed description reflects the alongside-signal behaviour", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await server.handleRequest({+ jsonrpc: JSONRPC_VERSION,+ id: 50,+ method: "tools/list",+ });+ const tools = (r as any).result.tools as ReadonlyArray<{+ name: string;+ inputSchema: { properties?: Record<string, { description?: string }> };+ }>;+ const feedback = tools.find((t) => t.name === "brain_feedback");+ expect(feedback).toBeDefined();+ const fcDesc =+ feedback!.inputSchema.properties?.["force_confirmed"]?.description ?? "";+ // The handler ALWAYS writes the inbox signal; with force_confirmed+ // it additionally materialises a confirmed preference. The earlier+ // "instead of an inbox signal" wording was incorrect.+ expect(fcDesc).toContain("alongside");+ expect(fcDesc).not.toMatch(/instead of an inbox signal/i);+ });+});++describe("brain_feedback", () => {+ test("writes a signal under Brain/inbox/ and returns path + id", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_feedback", {+ topic: "no-internal-abbrev",+ signal: "negative",+ principle: "Expand internal abbreviations on first use.",+ scope: "writing",+ source: ["[[Daily/2026.05.14]]"],+ raw: "Sergey pointed out OSB appeared without explanation.",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.kind).toBe("signal");+ expect(s.id).toMatch(/^sig-\d{4}-\d{2}-\d{2}-no-internal-abbrev$/);+ expect(s.path).toMatch(/^Brain\/inbox\/sig-.*\.md$/);+ expect(s.agent).toBe("claude");+ const file = join(vault, s.path);+ expect(existsSync(file)).toBe(true);+ const text = readFileSync(file, "utf8");+ expect(text).toContain("kind: brain-signal");+ expect(text).toContain("signal: negative");+ expect(text).toContain("topic: no-internal-abbrev");+ expect(text).toContain("Sergey pointed out OSB appeared");+ });++ test("force_confirmed: true creates a preference directly", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_feedback", {+ topic: "imperative-prompts",+ signal: "positive",+ principle: "Write prompts in imperative voice.",+ scope: "process",+ source: ["[[Daily/2026.05.14#prompts]]"],+ force_confirmed: true,+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.kind).toBe("preference");+ expect(s.id).toBe("pref-imperative-prompts");+ const prefFile = preferencePath(vault, "imperative-prompts");+ expect(existsSync(prefFile)).toBe(true);+ const text = readFileSync(prefFile, "utf8");+ expect(text).toContain("status: confirmed");+ expect(text).toContain("topic: imperative-prompts");+ });++ test("INVALID_PARAMS when required field missing", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_feedback", {+ // topic missing+ signal: "positive",+ principle: "x",+ });+ expect(r.error.code).toBe(-32602);+ });++ test("INVALID_PARAMS for invalid signal value", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_feedback", {+ topic: "x-rule",+ signal: "neutral",+ principle: "y",+ });+ expect(r.error.code).toBe(-32602);+ });+});++// ---------------------------------------------------------------------------+// brain_dream+// ---------------------------------------------------------------------------++describe("brain_dream", () => {+ test("no-op on empty vault returns changed=false", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_dream", {});+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.changed).toBe(false);+ expect(s.new_unconfirmed).toEqual([]);+ expect(s.confirmed).toEqual([]);+ expect(s.retired).toEqual([]);+ // No snapshot or log file should be written when nothing changed.+ expect(s.snapshot_path).toBeNull();+ expect(s.log_path).toBeNull();+ });++ test("promotes a cluster after 3 same-sign signals", async () => {+ // Seed three signals for the same topic so dream promotes them.+ for (let i = 0; i < 3; i++) {+ writeSignal(vault, {+ topic: "no-tabs-in-md",+ signal: "negative",+ agent: "claude",+ principle: "Use spaces, not tabs, in Markdown.",+ created_at: `2026-05-${10 + i}T10:00:00Z`,+ date: `2026-05-${10 + i}`,+ slug: `no-tabs-in-md-${i}`,+ scope: "writing",+ });+ }++ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_dream", {+ now: "2026-05-14T10:00:00Z",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.changed).toBe(true);+ expect(s.new_unconfirmed).toContain("pref-no-tabs-in-md");+ expect(s.moved_to_processed.length).toBe(3);+ expect(typeof s.run_id).toBe("string");+ expect(s.log_path).not.toBeNull();+ expect(s.snapshot_path).not.toBeNull();+ });++ test("dry_run computes plan without writing", async () => {+ for (let i = 0; i < 3; i++) {+ writeSignal(vault, {+ topic: "dry-run-rule",+ signal: "positive",+ agent: "claude",+ principle: "Dry-run test.",+ created_at: `2026-05-${10 + i}T10:00:00Z`,+ date: `2026-05-${10 + i}`,+ slug: `dry-run-rule-${i}`,+ });+ }+ const server = makeServer();+ await initialize(server);+ const dirs = brainDirs(vault);+ const inboxBefore = readdirSync(dirs.inbox).filter((n) =>+ n.endsWith(".md"),+ ).length;+ const prefsBefore = readdirSync(dirs.preferences).filter((n) =>+ n.endsWith(".md"),+ ).length;++ const r = await call(server, "brain_dream", {+ dry_run: true,+ now: "2026-05-14T10:00:00Z",+ });+ expect(r.result.isError).toBe(false);+ expect(r.result.structuredContent.dry_run).toBe(true);++ // Files unchanged on disk after a dry-run.+ const inboxAfter = readdirSync(dirs.inbox).filter((n) =>+ n.endsWith(".md"),+ ).length;+ const prefsAfter = readdirSync(dirs.preferences).filter((n) =>+ n.endsWith(".md"),+ ).length;+ expect(inboxAfter).toBe(inboxBefore);+ expect(prefsAfter).toBe(prefsBefore);+ });+});++// ---------------------------------------------------------------------------+// brain_apply_evidence+// ---------------------------------------------------------------------------++describe("brain_apply_evidence", () => {+ function seedPref(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `Rule for ${slug}`,+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed",+ evidenced_by: [`[[sig-2026-05-14-${slug}]]`],+ confirmed_at: null,+ scope: "writing",+ });+ }++ test("happy path appends to today's log and returns logged_at", async () => {+ seedPref("no-internal-abbrev");+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_apply_evidence", {+ pref_id: "pref-no-internal-abbrev",+ artifact: "[[Daily/2026.05.14#blog]]",+ result: "applied",+ note: "Expanded OSB on first use.",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.logged_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);+ expect(s.log_path.startsWith("Brain/log/")).toBe(true);+ expect(s.agent).toBe("claude");+ const file = join(vault, s.log_path);+ const text = readFileSync(file, "utf8");+ expect(text).toContain("[[pref-no-internal-abbrev]]");+ expect(text).toContain("applied");+ expect(text).toContain("Expanded OSB on first use.");+ });++ test("missing preference returns tool-level error (isError true)", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_apply_evidence", {+ pref_id: "pref-does-not-exist",+ artifact: "[[somewhere]]",+ result: "applied",+ });+ // Per design doc Β§9.2: "not an error condition" β surface a+ // friendly tool-level error envelope, not a JSON-RPC protocol error.+ expect(r.error).toBeUndefined();+ expect(r.result.isError).toBe(true);+ expect(r.result.content[0].text).toContain("preference not found");+ });++ test("INVALID_PARAMS for invalid result value", async () => {+ seedPref("x-rule");+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_apply_evidence", {+ pref_id: "pref-x-rule",+ artifact: "[[x]]",+ result: "maybe",+ });+ expect(r.error.code).toBe(-32602);+ });+});++// ---------------------------------------------------------------------------+// brain_digest+// ---------------------------------------------------------------------------++describe("brain_digest", () => {+ test("empty vault returns 'no changes' markdown", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_digest", {});+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.empty).toBe(true);+ expect(s.format).toBe("markdown");+ expect(s.content).toContain("no changes");+ });++ test("with confirmed prefs renders Markdown sections", async () => {+ // Seed a confirmed preference inside the digest window.+ writePreference(vault, {+ slug: "confirmed-rule",+ topic: "confirmed-rule",+ principle: "Confirmed test rule.",+ created_at: "2026-05-14T09:00:00Z",+ unconfirmed_until: "2026-05-14T09:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ confirmed_at: "2026-05-14T09:00:00Z",+ applied_count: 1,+ scope: "process",+ });+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_digest", {+ since: "2026-05-14T00:00:00Z",+ until: "2026-05-14T23:59:59Z",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.empty).toBe(false);+ expect(s.content).toContain("Brain digest");+ expect(s.content).toContain("Confirmed");+ });++ test("format=json returns valid JSON content", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_digest", { format: "json" });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.format).toBe("json");+ // Content must parse as JSON with the design-doc shape.+ const parsed = JSON.parse(s.content);+ expect(parsed.schema_version).toBe(1);+ expect(parsed.summary).toBeDefined();+ expect(parsed.summary.empty).toBe(true);+ });+});++// ---------------------------------------------------------------------------+// brain_query+// ---------------------------------------------------------------------------++describe("brain_query", () => {+ function seedPref(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `Rule for ${slug}`,+ created_at: "2026-05-14T10:00:00Z",+ unconfirmed_until: "2026-05-28T10:00:00Z",+ status: "unconfirmed",+ evidenced_by: [`[[sig-2026-05-14-${slug}]]`],+ confirmed_at: null,+ scope: "writing",+ });+ }++ test("by preference returns preference + evidence", async () => {+ seedPref("query-pref");+ // Append an apply-evidence event so the trail is non-empty.+ const server = makeServer();+ await initialize(server);+ await call(server, "brain_apply_evidence", {+ pref_id: "pref-query-pref",+ artifact: "[[doc]]",+ result: "applied",+ });+ const r = await call(server, "brain_query", {+ preference: "pref-query-pref",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.mode).toBe("preference");+ expect(s.preference.id).toBe("pref-query-pref");+ expect(s.evidence.length).toBe(1);+ expect(s.evidence[0].event_type).toBe("apply-evidence");+ });++ test("by topic returns signals + preference + log events", async () => {+ // Seed both a signal and a preference on the same topic.+ writeSignal(vault, {+ topic: "topic-query-rule",+ signal: "positive",+ agent: "claude",+ principle: "Whatever.",+ created_at: "2026-05-14T10:00:00Z",+ date: "2026-05-14",+ slug: "topic-query-rule",+ });+ seedPref("topic-query-rule");+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_query", {+ topic: "topic-query-rule",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.mode).toBe("topic");+ expect(s.topic).toBe("topic-query-rule");+ expect(s.signals.length).toBe(1);+ expect(s.preference).not.toBeNull();+ expect(s.preference.id).toBe("pref-topic-query-rule");+ });++ test("by since returns log events from the cutoff onward", async () => {+ seedPref("since-rule");+ const server = makeServer();+ await initialize(server);+ await call(server, "brain_apply_evidence", {+ pref_id: "pref-since-rule",+ artifact: "[[a]]",+ result: "applied",+ });+ const r = await call(server, "brain_query", {+ since: "1970-01-01T00:00:00Z",+ });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.mode).toBe("since");+ expect(s.events.length).toBeGreaterThanOrEqual(1);+ expect(s.events[0].event_type).toBe("apply-evidence");+ });++ test("requires exactly one selector", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_query", {});+ expect(r.error.code).toBe(-32602);++ const r2 = await call(server, "brain_query", {+ preference: "pref-x",+ topic: "y",+ });+ expect(r2.error.code).toBe(-32602);+ });++ test("unknown preference yields tool-level error (isError true)", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_query", {+ preference: "pref-not-here",+ });+ expect(r.error).toBeUndefined();+ expect(r.result.isError).toBe(true);+ expect(r.result.content[0].text).toContain("no preference");+ });+});++// ---------------------------------------------------------------------------+// brain_doctor+// ---------------------------------------------------------------------------++describe("brain_doctor", () => {+ test("clean vault returns ok=true with no issues", async () => {+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_doctor", {});+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ expect(s.ok).toBe(true);+ expect(s.errors).toEqual([]);+ expect(s.warnings).toEqual([]);+ });++ test("corrupted preference file surfaces as a doctor issue", async () => {+ // Write a preference file with broken YAML to trip a parse error.+ const dirs = brainDirs(vault);+ atomicWriteFileSync(+ join(dirs.preferences, "pref-broken.md"),+ "---\nkind: brain-preference\nid: pref-broken\n---\n# garbage with no required fields\n",+ );+ const server = makeServer();+ await initialize(server);+ const r = await call(server, "brain_doctor", { strict: true });+ expect(r.result.isError).toBe(false);+ const s = r.result.structuredContent;+ // At least one issue must be surfaced β either a warning or an error.+ expect(s.errors.length + s.warnings.length).toBeGreaterThan(0);+ });+});++// ---------------------------------------------------------------------------+// Advertised-tool deprecation guard+// ---------------------------------------------------------------------------++describe("deprecated MCP tools β advertised list", () => {+ test("`event_log_append` and `second_brain_capture` are NOT in the registry", () => {+ const names = new Set(buildToolTable().map((t) => t.name));+ expect(names.has("event_log_append")).toBe(false);+ expect(names.has("second_brain_capture")).toBe(false);+ });++ test("all six Brain tools are advertised", () => {+ const names = new Set(buildToolTable().map((t) => t.name));+ for (const expected of [+ "brain_feedback",+ "brain_dream",+ "brain_apply_evidence",+ "brain_digest",+ "brain_query",+ "brain_doctor",+ ]) {+ expect(names.has(expected)).toBe(true);+ }+ });+});diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.tsindex f69c0aa7..423cf9c5 100644--- a/tests/mcp/mcp.test.ts+++ b/tests/mcp/mcp.test.ts@@ -86,7 +86,7 @@ describe("handshake", () => {expect(result.protocolVersion).toBe(PROTOCOL_VERSION);});- test("instructions embed resolved agent identity", async () => {+ test("instructions embed resolved agent identity and Brain tools", async () => {const vault = join(tmp, "vault");mkdirSync(vault);const config = join(tmp, "config.yaml");@@ -95,8 +95,12 @@ describe("handshake", () => {const r = (await initialize(server))! as any;const inst = r.result.instructions as string;expect(inst).toContain("@hermes-vps-agent");- expect(inst).toContain("event_log_append");- expect(inst).toContain("DO NOT");+ // v0.9.0+ β instructions advertise Brain tools, not the legacy+ // event_log_append / second_brain_capture path.+ expect(inst).toContain("brain_feedback");+ expect(inst).toContain("brain_apply_evidence");+ expect(inst).not.toContain("event_log_append");+ expect(inst).not.toContain("second_brain_capture");});test("negotiates alternate client version", async () => {@@ -129,7 +133,7 @@ describe("handshake", () => {});describe("tool listing", () => {- test("advertises the core and Pay Memory tools", async () => {+ test("advertises the core, Brain, and Pay Memory tools (v0.9.0+)", async () => {const server = new MCPServer({ vault: tmp });await initialize(server);const r = (await server.handleRequest({@@ -140,11 +144,18 @@ describe("tool listing", () => {const names = new Set(r.result.tools.map((t: { name: string }) => t.name));expect(names).toEqual(new Set([+ // Core read/health (writable legacy tools removed in v0.9.0)."second_brain_status","second_brain_query",- "second_brain_capture",- "event_log_append","vault_health",+ // Brain (v0.9.0).+ "brain_feedback",+ "brain_dream",+ "brain_apply_evidence",+ "brain_digest",+ "brain_query",+ "brain_doctor",+ // Pay Memory (unchanged)."payment_memory_init","payment_receipt_append","asset_capture",@@ -155,6 +166,9 @@ describe("tool listing", () => {"payment_request_consume",]),);+ // Explicit grep: legacy writable tools are no longer advertised.+ expect(names.has("event_log_append")).toBe(false);+ expect(names.has("second_brain_capture")).toBe(false);for (const t of r.result.tools) {expect(t.inputSchema.type).toBe("object");}@@ -188,248 +202,25 @@ describe("tool calls", () => {expect(s.pages.some((p: { title: string }) => p.title.includes("Sandbox"))).toBe(true);});- test("second_brain_capture writes note with frontmatter", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const server = new MCPServer({ vault });- await initialize(server);- const r = (await callTool(server, "second_brain_capture", {- title: "Hello World",- content: "# Body\n\ntext",- tags: ["draft", "demo"],- })) as any;- const s = r.result.structuredContent;- const note = join(vault, "AI Wiki", "notes", "hello-world.md");- const text = readFileSync(note, "utf8");- expect(text).toContain("title: Hello World");- expect(text).toContain("tags: [draft, demo]");- expect(text).toContain("# Body");- expect(s.slug).toBe("hello-world");- });-- test("second_brain_capture rejects existing note without overwrite", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const server = new MCPServer({ vault });- await initialize(server);- const args = { title: "Same Title", content: "first" };- const first = (await callTool(server, "second_brain_capture", args)) as any;- expect(first.result.isError).toBe(false);- const second = (await callTool(server, "second_brain_capture", args, 100)) as any;- expect(second.result.isError).toBe(true);- expect(second.result.content[0].text).toContain("already exists");- });-- test("second_brain_capture rejects empty title", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const server = new MCPServer({ vault });- await initialize(server);- const r = (await callTool(server, "second_brain_capture", {- title: " ",- content: "body",- })) as any;- expect(r.error.code).toBe(-32602);- });-- test("event_log_append writes daily note", async () => {- const vault = tmp;- const server = new MCPServer({ vault });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "via mcp",- agent: "mcp-test",- date: "2026.05.06",- time: "11:42",- })) as any;- expect(r.result.isError).toBe(false);- const s = r.result.structuredContent;- expect(s.agent).toBe("mcp-test");- const daily = join(vault, "Daily", "2026.05.06.md");- expect(readFileSync(daily, "utf8")).toContain("- 11:42 β @mcp-test β via mcp");- });-- test("event_log_append strips leading @ in agent", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const server = new MCPServer({ vault });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "with-at-prefix",- agent: "@hermes-vps-agent",- date: "2026.05.06",- time: "11:55",- })) as any;- expect(r.result.isError).toBe(false);- const s = r.result.structuredContent;- expect(s.agent).toBe("hermes-vps-agent");- const daily = join(vault, "Daily", "2026.05.06.md");- const text = readFileSync(daily, "utf8");- expect(text).toContain("- 11:55 β @hermes-vps-agent β with-at-prefix");- expect(text).not.toContain("@@");- });-- test("placeholder agent values fall back to default", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const config = join(tmp, "config.yaml");- writeFileSync(config, "agent_name: hermes-vps-agent\n");- const server = new MCPServer({ vault, configPath: config });+ // `second_brain_capture` and `event_log_append` are no longer+ // advertised through MCP in v0.9.0 (design doc Β§11.1). The handler+ // functions remain in `src/mcp/tools.ts` for shell-side use+ // (`o2b append-event`); their behaviour is covered by the CLI / core+ // event-log tests. Here we only assert that the tool registry no+ // longer exposes them.+ test("removed legacy writable tools return method-not-found", async () => {+ const server = new MCPServer({ vault: tmp });await initialize(server);- const cases = [- "agent",- "@agent",- "AGENT",- " @agent ",- "assistant",- "@assistant",- "Assistant",- "claude",- "claude-code",- "codex",- "Codex",- "@codex",- "codex-cli",- "codex-exec",- "GPT",- "gpt-5",- "ai",- "Bot",- "model",- "hermes",- "openclaw",- ];- for (const trash of cases) {- const r = (await callTool(server, "event_log_append", {- message: `trash:${trash}`,- agent: trash,- date: "2026.05.06",- time: "12:30",+ for (const name of ["second_brain_capture", "event_log_append"]) {+ const r = (await callTool(server, name, {+ title: "x",+ content: "y",+ message: "z",})) as any;- expect(r.result.isError).toBe(false);- expect(r.result.structuredContent.agent).toBe("hermes-vps-agent");+ expect(r.error.code).toBe(-32601);}});- test("empty optional strings treated as missing", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const server = new MCPServer({ vault });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "with-empty-optionals",- agent: "",- date: "",- time: "",- })) as any;- expect(r.result.isError).toBe(false);- const s = r.result.structuredContent;- expect(s.date).toBeNull();- expect(s.time).toBeNull();- });-- test("uses configured timezone for daily file", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const config = join(tmp, "config.yaml");- writeFileSync(config, 'agent_name: "hermes-vps-agent"\ntimezone: "Europe/Belgrade"\n');- const server = new MCPServer({ vault, configPath: config });- await initialize(server);-- // Capture local-tz wallclock BEFORE the call to avoid midnight rollover.- const fmt = new Intl.DateTimeFormat("en-CA", {- timeZone: "Europe/Belgrade",- year: "numeric",- month: "2-digit",- day: "2-digit",- });- const expectedDate = fmt.format(new Date()).replace(/-/g, ".");-- const r = (await callTool(server, "event_log_append", { message: "tz-test" })) as any;- expect(r.result.isError).toBe(false);- const expectedFile = join(vault, "Daily", `${expectedDate}.md`);- const text = readFileSync(expectedFile, "utf8");- expect(text).toContain("β @hermes-vps-agent β tz-test");- });-- test("VAULT_TIMEZONE env wins over config", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const config = join(tmp, "config.yaml");- writeFileSync(config, 'timezone: "UTC"\n');- process.env["VAULT_TIMEZONE"] = "Europe/Belgrade";- const server = new MCPServer({ vault, configPath: config });- await initialize(server);- const fmt = new Intl.DateTimeFormat("en-CA", {- timeZone: "Europe/Belgrade",- year: "numeric",- month: "2-digit",- day: "2-digit",- });- const expectedDate = fmt.format(new Date()).replace(/-/g, ".");- const r = (await callTool(server, "event_log_append", {- message: "env-tz-test",- agent: "tester",- })) as any;- expect(r.result.isError).toBe(false);- const expectedFile = join(vault, "Daily", `${expectedDate}.md`);- expect(() => readFileSync(expectedFile, "utf8")).not.toThrow();- });-- test("invalid config timezone falls back silently", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const config = join(tmp, "config.yaml");- writeFileSync(config, 'timezone: "Not/A/Real/Zone"\n');- const server = new MCPServer({ vault, configPath: config });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "fallback",- agent: "tester",- })) as any;- expect(r.result.isError).toBe(false);- });-- test("uses agent_name from config when no env or arg", async () => {- const vault = join(tmp, "vault");- mkdirSync(vault);- const config = join(tmp, "config.yaml");- writeFileSync(config, "agent_name: openclaw-main\n");- const server = new MCPServer({ vault, configPath: config });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "from-config-default",- date: "2026.05.06",- time: "12:00",- })) as any;- expect(r.result.isError).toBe(false);- expect(r.result.structuredContent.agent).toBe("openclaw-main");- const daily = join(vault, "Daily", "2026.05.06.md");- expect(readFileSync(daily, "utf8")).toContain("- 12:00 β @openclaw-main β from-config-default");- });-- test("event_log_append rejects invalid time", async () => {- const server = new MCPServer({ vault: tmp });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "x",- time: "99:99",- })) as any;- expect(r.result.isError).toBe(true);- expect(r.result.content[0].text).toContain("HH:MM");- });-- test("event_log_append rejects invalid date paths", async () => {- const server = new MCPServer({ vault: tmp });- await initialize(server);- const r = (await callTool(server, "event_log_append", {- message: "x",- date: "../AI Wiki/notes/pwn",- })) as any;- expect(r.result.isError).toBe(true);- expect(r.result.content[0].text).toContain("YYYY.MM.DD");- });-test("vault_health runs doctor", async () => {const vault = createSandboxVault(tmp);const repo = createPluginRepo(tmp, true);@@ -476,7 +267,8 @@ describe("stdio loop", () => {const list = JSON.parse(lines[1]!);expect(init.id).toBe(1);expect(list.id).toBe(2);- expect(list.result.tools.length).toBe(13);+ // v0.9.0: 3 core (status/query/health) + 6 Brain + 8 Pay Memory = 17.+ expect(list.result.tools.length).toBe(17);});test("returns parse error for invalid JSON", async () => {