Skip to content

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

feat: cjk schema lifecycle recovery - CJK search, schema admin, lifecycle hooks, watchdog (#53)

Sol Aitken40d4e2bcf4ad
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 92869475..a5c9971c 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.25.0",
+ "version": "0.26.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.json
index 8d2e913d..a1344476 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.25.0",
+ "version": "0.26.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.md
index 9e8a3284..7478cc1c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,51 @@ 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.26.0] - 2026-05-30
+
+CJK search, schema administration, real-time lifecycle capture, and safe
+watchdog recovery probes. This release completes the runtime schema pack work
+from v0.25.0 and makes recovery/capture paths explicit and auditable.
+
+### Added
+
+- CJK-aware search indexing and query tokenization for Chinese/Japanese/Korean
+ text. FTS stores expanded shadow content for recall while returned snippets
+ keep the original vault text clean; optional `@node-rs/jieba` and
+ `tiny-segmenter` improve segmentation when available, with deterministic
+ fallback n-grams when they are not.
+- Atomic schema mutation engine for all schema primitives: add/remove/update
+ types, aliases, prefixes, link types, extractability, and expert routing.
+ Writes to `Brain/_brain.yaml` are file-locked, atomically replaced, validated
+ before commit, and audited under `Brain/log/schema-mutations` JSONL roots.
+- Schema admin CLI and MCP surfaces: `o2b brain schema stats|lint|graph|explain|orphans|apply|sync`
+ plus MCP tools `get_active_schema_pack`, `list_schema_packs`, `schema_stats`,
+ `schema_lint`, `schema_graph`, `schema_explain_type`, `schema_review_orphans`,
+ `schema_apply_mutations`, and `reload_schema_pack`.
+- `skills/schema-author`, a dedicated agent skill for reviewing and applying
+ schema changes through the audited mutation path.
+- Real-time lifecycle capture through `hooks/session-capture.ts` and
+ `o2b brain session-hook`. SessionStart, UserPromptSubmit, PostToolUse,
+ Stop, PostCompact, and SessionEnd events now produce non-blocking lifecycle
+ audit/log observations; prompt `@osb` markers and `brain_feedback` tool calls
+ are captured immediately through the existing signal dedup boundary.
+- `o2b brain watchdog` and MCP `brain_watchdog` for Brain config/dir/search-index
+ probes, exponential backoff metadata, safe directory remediation, and snapshot
+ restore refusal unless restore intent and force are explicit.
+
+### Changed
+
+- MCP full-server tool count is now 57 after adding schema admin tools and
+ `brain_watchdog`.
+- `o2b brain schema` is now an admin command group; the original read-only
+ report remains available as the default `report` mode.
+
+### Notes
+
+- `bun run lint` remains warning-only on the existing repository baseline.
+- `bun run fmt:check` still fails on the pre-existing formatter baseline; files
+ touched by this release were formatted with targeted `oxfmt --write`.
+
## [0.25.0] - 2026-05-30
Runtime schema packs foundation. Vaults can now declare custom taxonomy tokens
@@ -2182,7 +2227,7 @@ with `source_type: inline`, the source-file wikilink in `source`,
and a `dedup_hash`over the normalised payload. After capture
the source line is annotated`@osbβœ“ [[sig-...]]`(inline form)
or the info-string flips to`osb-checked`with a`<!-- @osbβœ“
- [[sig-...]] -->`comment line (block form), making re-runs
+ [[sig-...]] -->`comment line (block form), making re-runs
idempotent. Default ignore set covers`Brain/`, `.git`,
`node_modules`, `.obsidian`, `.trash`, `.stversions`,
`.open-second-brain`; additional excludes via `--exclude`,
@@ -3528,6 +3573,10 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.26.0]: https://github.com/itechmeat/open-second-brain/compare/v0.25.0...v0.26.0
+[0.25.0]: https://github.com/itechmeat/open-second-brain/compare/v0.24.0...v0.25.0
+[0.24.0]: https://github.com/itechmeat/open-second-brain/compare/v0.23.0...v0.24.0
+[0.23.0]: https://github.com/itechmeat/open-second-brain/compare/v0.22.0...v0.23.0
[0.22.0]: https://github.com/itechmeat/open-second-brain/compare/v0.21.0...v0.22.0
[0.21.0]: https://github.com/itechmeat/open-second-brain/compare/v0.20.0...v0.21.0
[0.20.0]: https://github.com/itechmeat/open-second-brain/compare/v0.19.0...v0.20.0
diff --git a/README.md b/README.md
index 0278df43..13c89fc8 100644
--- a/README.md
+++ b/README.md
@@ -99,21 +99,23 @@ Three repeat signals on the same topic graduate to a confirmed rule. Evidence sh
The capabilities you actually feel day to day:
-| # | Feature | What it means for you |
-| --- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | Your memory, in your Obsidian vault | Every rule the agent learns about you is a Markdown file you can open, read, and edit. Wikilinks, backlinks, and the graph view in Obsidian all work β€” no separate UI to learn. |
-| 2 | `dream` - the agent learns what you actually want | The nightly `dream` pass turns repeat corrections into rules: three signals on the same topic graduate to a confirmed preference. Its confidence rises every time the agent applies the rule and drops when it slips. No LLM inside the algorithm - counters and atomic file moves, nothing else. |
-| 3 | One brain, every agent | Hermes Agent, Claude Code, Codex, Cursor, Aider, opencode, kiro, Copilot CLI, Gemini CLI, Pi - they all read the same memory. Teach one of them a rule and the next one already knows; `brain_agent_query` and `brain_agent_diff` let you inspect which agent contributed what. |
-| 4 | Teach a rule in one line | Drop `@osb feedback negative topic=... principle="..."` into any note. Next time `o2b brain scan-inline` runs (or you call it manually) the marker becomes a real taste signal in `Brain/inbox/` and the note gets a `@osbβœ“` checkmark so re-runs skip it. |
-| 5 | Look back at how your AI grew | The time axis surfaces how the agent's view of you evolved. `o2b brain evolution` walks a single preference's life from first signal to confirmed to retired; `o2b brain daily` / `weekly` / `monthly` summarise what changed; `o2b brain intent-review` previews whether signal clusters are ready before the next `dream`; `o2b brain retention` recommends keep/improve/park/prune actions without deleting anything. |
-| 6 | Browse your memory as a graph | `o2b brain explorer` opens a force-directed HTML graph of every rule, every link, every retirement. Preference files can now declare typed relationships such as `depends_on:` and `refines:`, plus `memory_layer` / `memory_branch` labels and optional `schema_type:` taxonomy metadata; `o2b brain schema` audits those tokens without changing the Markdown source of truth. Double-click a node β€” Obsidian opens the underlying note. |
-| 7 | Undo the agent if it gets it wrong | Every Brain mutation lands a verified snapshot before touching anything. One command (`o2b brain rollback <id>`) restores yesterday's state, and drift detection refuses to clobber unintended local edits. |
-| 8 | Pin, merge, retire by hand | When a rule is wrong, you fix it. `o2b brain pin` keeps a good one safe from auto-retire, `merge` folds duplicates, `reject` puts a bad rule in the bin with a reason. The CLI is the operator's seat. |
-| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open` β€” SQLite + FTS5 and an optional semantic layer, fused and then sharpened by a recall-quality suite: MMR diversity so near-duplicates do not crowd the top, link-graph traversal that surfaces notes one hop from a hit, entity-boosting for proper-noun precision, and header-anchored chunking so a mid-document chunk keeps its section context. Every result carries a `why_retrieved` breakdown of the layers that ranked it. |
-| 10 | Pay Memory β€” audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |
+| # | Feature | What it means for you |
+| --- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | Your memory, in your Obsidian vault | Every rule the agent learns about you is a Markdown file you can open, read, and edit. Wikilinks, backlinks, and the graph view in Obsidian all work β€” no separate UI to learn. |
+| 2 | `dream` - the agent learns what you actually want | The nightly `dream` pass turns repeat corrections into rules: three signals on the same topic graduate to a confirmed preference. Its confidence rises every time the agent applies the rule and drops when it slips. No LLM inside the algorithm - counters and atomic file moves, nothing else. |
+| 3 | One brain, every agent | Hermes Agent, Claude Code, Codex, Cursor, Aider, opencode, kiro, Copilot CLI, Gemini CLI, Pi - they all read the same memory. Teach one of them a rule and the next one already knows; `brain_agent_query` and `brain_agent_diff` let you inspect which agent contributed what. |
+| 4 | Teach a rule in one line | Drop `@osb feedback negative topic=... principle="..."` into any note. Next time `o2b brain scan-inline` runs (or you call it manually) the marker becomes a real taste signal in `Brain/inbox/` and the note gets a `@osbβœ“` checkmark so re-runs skip it. |
+| 5 | Look back at how your AI grew | The time axis surfaces how the agent's view of you evolved. `o2b brain evolution` walks a single preference's life from first signal to confirmed to retired; `o2b brain daily` / `weekly` / `monthly` summarise what changed; `o2b brain intent-review` previews whether signal clusters are ready before the next `dream`; `o2b brain retention` recommends keep/improve/park/prune actions without deleting anything. |
+| 6 | Browse and govern your memory schema | `o2b brain explorer` opens a force-directed HTML graph of every rule, every link, every retirement. Preference files can declare typed relationships such as `depends_on:` and `refines:`, plus `memory_layer` / `memory_branch` labels and optional `schema_type:` taxonomy metadata; `o2b brain schema` stats, lint, graph, explain, orphans, and apply audit and mutate those tokens through locked, audited writes. Double-click a node β€” Obsidian opens the underlying note. |
+| 7 | Undo the agent if it gets it wrong | Every Brain mutation lands a verified snapshot before touching anything. One command (`o2b brain rollback <id>`) restores yesterday's state, and drift detection refuses to clobber unintended local edits. |
+| 8 | Pin, merge, retire by hand | When a rule is wrong, you fix it. `o2b brain pin` keeps a good one safe from auto-retire, `merge` folds duplicates, `reject` puts a bad rule in the bin with a reason. The CLI is the operator's seat. |
+| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open` β€” SQLite + FTS5 and an optional semantic layer, with CJK-aware token expansion for unspaced Chinese/Japanese/Korean text. Recall is sharpened by MMR diversity, link-graph traversal, entity boosting, and header-anchored chunking; every result carries a `why_retrieved` breakdown of the layers that ranked it. |
+| 10 | Pay Memory β€” audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |
These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio), and the v0.18.0 MCP context economy (a per-tool preview budget that returns a bounded inline preview and parks the full payload in a vault-local artifact the agent fetches on demand with `brain_artifact_get`, plus a `recall_hint` one-liner on search results), and the v0.19.0 typed graph semantics (typed frontmatter relationships - `related` / `extends` / `contradicts` / `superseded_by` - that surface inline on search results, a `visibility:` scoping axis for `brain_search`, and a `brain_mcp_landscape` view of the Model Context Protocol servers configured across the vault), and the v0.20.0 Recall and Ranking Quality suite (a configurable Weibull recency-decay curve, structural query-intent classification that re-weights ranking by query shape, language-agnostic synonym expansion via local co-occurrence, per-memory and total recall character budgets for `brain_context_pack`, a persistent query cache that self-invalidates on a corpus-generation change, and a `brain_pre_compress_pack` tool that returns a budgeted top-preferences addendum for a host runtime to inject before context compression), and the v0.21.0 Brain Lifecycle Suite (a per-preference mutation audit trail keyed by preference id - create / promote / update / retire / merge with revision + content-hash before/after, via `o2b brain audit` and `brain_audit`; a multi-phase `dream` pipeline that names its close / reconcile / synthesize / heal / log seams and reports a structured per-phase summary without rewriting the proven internals; deterministic reconcile-phase domain classification that buckets contradictions into claims / entity / decisions / source-freshness, auto-resolves only the decisive source-freshness case, and surfaces the rest as open questions instead of forcing a merge; a budgeted `o2b brain morning-brief` / `brain_morning_brief` session-start summary of top preferences, recent open questions, and recent notes; language-agnostic ISO-8601 temporal extraction that fills preference validity windows from signal text; and opt-in heal-phase vault enrichment that links exact title mentions across user pages), and the v0.22.0 Vault portability + session economy suite (a deterministic lossless session codec - `expand(compress(x)) === x` for all input, opt-in on the signal store and exposed as `o2b brain codec`; an `o2b brain sources` / `brain_sources` read-only dashboard of signals by agent and source type; vault-map `{{role}}` tokens resolved via an optional `Brain/_vault-map.yaml` and wired into scan-inline read paths and graph import; named multi-vault profiles with `o2b vault profile` + a `brain_switch_vault` tool, activated by a pointer in config; and `o2b brain graph-export` / `graph-import` for moving a vault's knowledge graph between layouts with skip/overwrite/merge conflict modes). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.
+The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes.
+
## CLI
```bash
@@ -128,7 +130,8 @@ o2b brain monthly --month 2026-05 --json # Month-level Brain synthesis
o2b brain audit pref-foo --json # Full mutation trail for one preference
o2b brain morning-brief --json # Session-start summary (prefs, open questions, notes)
o2b brain sources --json # Per-source signal dashboard
-o2b brain schema --json # Runtime schema vocabulary + usage report
+o2b brain schema lint --json # Runtime schema vocabulary + usage/admin findings
+o2b brain watchdog --json # Brain probes + safe recovery recommendations
o2b brain graph-export --out graph.json # Export the vault knowledge graph
o2b brain semantics-backfill --json # Dry-run typed preference-edge repair proposals
o2b vault profile switch work # Activate a named multi-vault profile
@@ -151,7 +154,8 @@ Full list (~50 verbs across `o2b`, `o2b brain`, `o2b vault`, `o2b discipline`, P
- Secrets are not supposed to live in the vault. Daily logs and config exports go through a best-effort redactor for common secret-name patterns.
- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`.
- Lifecycle review commands (`intent-review`, `retention`, `monthly`) are read-only. Retention emits recommendations only; it never deletes, moves, or edits Brain artifacts.
-- Hooks (Claude Code, Codex) only inject text into the agent's context; they never write to the vault directly.
+- Hooks (Claude Code, Codex) inject active context and capture explicit prompt markers / `brain_feedback` tool calls through the same signal dedup boundary; lifecycle observations are audited/logged and never block the runtime.
+- `o2b brain watchdog` and `brain_watchdog` are probe-first. They recommend search-index repair and can create missing Brain directories only when remediation is explicit; snapshot restore is refused unless restore intent and force are both explicit.
- Text written through Brain/Pay Memory redaction strips `<private>...</private>` regions before storage and masks secret-shaped assignments such as `api_key=...`.
## Updating
diff --git a/bun.lock b/bun.lock
index 18f3f7d1..5fe9bd95 100644
--- a/bun.lock
+++ b/bun.lock
@@ -16,11 +16,51 @@
"typescript": "^5.5.0",
},
"optionalDependencies": {
+ "@node-rs/jieba": "^2.0.1",
"sqlite-vec": "^0.1.9",
+ "tiny-segmenter": "^0.2.0",
},
},
},
"packages": {
+ "@emnapi/core": ["@emnapi/[email protected]", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.1", "tslib": "^2.4.0" } }, "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw=="],
+
+ "@emnapi/runtime": ["@emnapi/[email protected]", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA=="],
+
+ "@emnapi/wasi-threads": ["@emnapi/[email protected]", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w=="],
+
+ "@napi-rs/wasm-runtime": ["@napi-rs/[email protected]", "", { "dependencies": { "@emnapi/core": "^1.4.3", "@emnapi/runtime": "^1.4.3", "@tybys/wasm-util": "^0.10.0" } }, "sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ=="],
+
+ "@node-rs/jieba": ["@node-rs/[email protected]", "", { "optionalDependencies": { "@node-rs/jieba-android-arm-eabi": "2.0.1", "@node-rs/jieba-android-arm64": "2.0.1", "@node-rs/jieba-darwin-arm64": "2.0.1", "@node-rs/jieba-darwin-x64": "2.0.1", "@node-rs/jieba-freebsd-x64": "2.0.1", "@node-rs/jieba-linux-arm-gnueabihf": "2.0.1", "@node-rs/jieba-linux-arm64-gnu": "2.0.1", "@node-rs/jieba-linux-arm64-musl": "2.0.1", "@node-rs/jieba-linux-x64-gnu": "2.0.1", "@node-rs/jieba-linux-x64-musl": "2.0.1", "@node-rs/jieba-wasm32-wasi": "2.0.1", "@node-rs/jieba-win32-arm64-msvc": "2.0.1", "@node-rs/jieba-win32-ia32-msvc": "2.0.1", "@node-rs/jieba-win32-x64-msvc": "2.0.1" } }, "sha512-tnfzXOMqzVQF2dSKMhPC9HrHzzWmN6KheL/zYtGenhOpq/bCKHJWVASSggEnHlkmHgXGeIJHR2N/IuPzewz1BQ=="],
+
+ "@node-rs/jieba-android-arm-eabi": ["@node-rs/[email protected]", "", { "os": "android", "cpu": "arm" }, "sha512-tavsIaxybnlA9tRbJ+oc3NW3zhx0d5rNiCGdpIdGWjflwS7HyeUTVAZmAFDlg58Mc6EjTdVKZH+RolBbAJtgcQ=="],
+
+ "@node-rs/jieba-android-arm64": ["@node-rs/[email protected]", "", { "os": "android", "cpu": "arm64" }, "sha512-AwdyqKvVNuSDnDq3anUfq+nJ5J/kzXjkfbr/1WY6TfaAlTNuuGVskuQv72/wIx/jn7NoXfm/UPuJrWYG16NC6w=="],
+
+ "@node-rs/jieba-darwin-arm64": ["@node-rs/[email protected]", "", { "os": "darwin", "cpu": "arm64" }, "sha512-10+nwGQ6KzXXJlIL/sELA6Fi6m7eJ7xJksBiKuw1kxKUgaJwtVfAG0iqRF+NRQv0Sdq7r3k5ew9K9y0+IYaEcA=="],
+
+ "@node-rs/jieba-darwin-x64": ["@node-rs/[email protected]", "", { "os": "darwin", "cpu": "x64" }, "sha512-IJ5RK0X/uPQa1XRmTvwKSieya+w1IJeiKLw0EekoBFJKybXQdvo8/uqM/8z2eVJ8vQxW9X6K2vkVGFvYQa9dYA=="],
+
+ "@node-rs/jieba-freebsd-x64": ["@node-rs/[email protected]", "", { "os": "freebsd", "cpu": "x64" }, "sha512-yg7vyhqzP2weJu5DJ3q9q4pb0b4GWWRwcv54zK7MSSA6KNJ/uQv2a4R9/qmptLU/fZv14gWuJBEMFdL7y1Dv2w=="],
+
+ "@node-rs/jieba-linux-arm-gnueabihf": ["@node-rs/[email protected]", "", { "os": "linux", "cpu": "arm" }, "sha512-fxQYunS7w2tv8XV9GigkWJPzHnbcw6tjrUdDu5/qU0FdQVEzGuEYG85DjlNf8lZTDGSUKHBVyAQs7bBIvq8yqg=="],
+
+ "@node-rs/jieba-linux-arm64-gnu": ["@node-rs/[email protected]", "", { "os": "linux", "cpu": "arm64" }, "sha512-VnLU630hQIyO/fwyxh2vqZi72mO+hXkVUC3jVLPfOAlppinmsGX9N81tpTPUK3840hbV8WLtbYTWN1XodI38eg=="],
+
+ "@node-rs/jieba-linux-arm64-musl": ["@node-rs/[email protected]", "", { "os": "linux", "cpu": "arm64" }, "sha512-K4EDyNixSLVdTNYnHwD+7I/ytvzpo7tt+vdCLqwQViiek2PMpL/FFRvA39uU2tk99jXIxvkczdxARG20BRZppg=="],
+
+ "@node-rs/jieba-linux-x64-gnu": ["@node-rs/[email protected]", "", { "os": "linux", "cpu": "x64" }, "sha512-sq3J6L2ANTE25I9eVFq/nb57OtXcvUIeUD1CTKJxwgTKIVmcB2LyOZpWf20AjHRUfbMER9Klqg5dgyyO+Six+w=="],
+
+ "@node-rs/jieba-linux-x64-musl": ["@node-rs/[email protected]", "", { "os": "linux", "cpu": "x64" }, "sha512-0zfP9Qy68yEXrhBFknfhF6WUJDPU/8eRuyIrkMGdMjfRpxhpSbr2fMfnsqhOQLvhuK4w3iDFvTy4t5d0s6JKMA=="],
+
+ "@node-rs/jieba-wasm32-wasi": ["@node-rs/[email protected]", "", { "dependencies": { "@napi-rs/wasm-runtime": "^0.2.5" }, "cpu": "none" }, "sha512-7I5rJya5rlQNJIhv8PvPzIVT1/gVc0vFzHmlfRGwCPGDJ3tHVxkSPW34dDx3OgDmbIeadNpmgIyC1RaS9djPJg=="],
+
+ "@node-rs/jieba-win32-arm64-msvc": ["@node-rs/[email protected]", "", { "os": "win32", "cpu": "arm64" }, "sha512-Aj/2EwYSaPgAbKnSl+vKM/2kOaZNMZWnShiZzbSNyzlLy3eIOyOYVLbYRDno4547KngRxer8uzROhIQIwXwkvw=="],
+
+ "@node-rs/jieba-win32-ia32-msvc": ["@node-rs/[email protected]", "", { "os": "win32", "cpu": "ia32" }, "sha512-tpJt3uuBlGrcOInQLTYvcgamQgfadl5cwExLYU+CX9rXKpXLDO31dIujUDBgNWoiQq3tOiU1/AKbT7ZdNd4lBQ=="],
+
+ "@node-rs/jieba-win32-x64-msvc": ["@node-rs/[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-LDOyo2/2CO8UnpSGLJdgqtH8mOnsABPhNxkfIky7UT9cyLEzOaU44nbA5YzPGpBI3qzMbWcwJYQsjBcgK2VqAg=="],
+
"@oxfmt/binding-android-arm-eabi": ["@oxfmt/[email protected]", "", { "os": "android", "cpu": "arm" }, "sha512-KrMQRdMi/upr81qT4ijK6X6BNp6jqpMY7FwILQnwIy9QLc3qpnhUx5rsCLGzn4ewsCQ0CNAspN2ogmP1GXLyLw=="],
"@oxfmt/binding-android-arm64": ["@oxfmt/[email protected]", "", { "os": "android", "cpu": "arm64" }, "sha512-r4ixS/PeUpAFKgrpDoZ5pSkthjZzVzKd95525Aazj+aOv9H4ulK5zYHGb7wFY5n5kZxHK8TbOJUZgoEb1ohddQ=="],
@@ -97,6 +137,8 @@
"@oxlint/binding-win32-x64-msvc": ["@oxlint/[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-6hMpyDWQ2zGA1OXFKBrdYMUveUCO8UJhkO6JdwZPd78xIdHZNhjx+pib+4fC2Cljuhjyl0QwA2F3df/bs4Bp6A=="],
+ "@tybys/wasm-util": ["@tybys/[email protected]", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg=="],
+
"@types/bun": ["@types/[email protected]", "", { "dependencies": { "bun-types": "1.3.13" } }, "sha512-9fqXWk5YIHGGnUau9TEi+qdlTYDAnOj+xLCmSTwXfAIqXr2x4tytJb43E9uCvt09zJURKXwAtkoH4nLQfzeTXw=="],
"@types/node": ["@types/[email protected]", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-9v00a+dn2yWVsYDEunWC4g/TcRKVq3r8N5FuZp7u0SGrPvdN9c2yXI9bBuf5Fl0hNCb+QTIePTn5pJs2pwBOQQ=="],
@@ -131,8 +173,12 @@
"sqlite-vec-windows-x64": ["[email protected]", "", { "os": "win32", "cpu": "x64" }, "sha512-y3gEIyy/17bq2QFPQOWLE68TYWcRZkBQVA2XLrTPHNTOp55xJi/BBBmOm40tVMDMjtP+Elpk6UBUXdaq+46b0Q=="],
+ "tiny-segmenter": ["[email protected]", "", {}, "sha512-m+aTJQ/CUBKurLaJRpLmJiwcL+Gpkzft5ZYnRU9AkuO45Y/k/2iJmuLEbN1XLrq6N3kDVyIUCCeqRzQx0feBag=="],
+
"tinypool": ["[email protected]", "", {}, "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw=="],
+ "tslib": ["[email protected]", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
+
"typescript": ["[email protected]", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
"undici-types": ["[email protected]", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
diff --git a/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/claude.md b/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/claude.md
new file mode 100644
index 00000000..e3a68da4
--- /dev/null
+++ b/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/claude.md
@@ -0,0 +1,38 @@
+### Variant 1: Four Isolated Vertical Slices
+- **Approach**: Treat each task as a self-contained module that touches only its own existing boundary β€” CJK at `search/schema.ts`+`indexer.ts`, schema mutation at `schema-vocab.ts`+a new `schema-mutate.ts`, session hooks as a new `sessions/hooks.ts` adapter feeding `writeSignal`, watchdog as a standalone gateway background task. Each ships behind its own default-off config key with no shared scaffolding between them. The PR is the sum of four independently reviewable diffs.
+- **Trade-offs**:
+ - Pro: maximum reviewability and rollback granularity; each slice can be reverted without touching the others.
+ - Pro: lowest coupling risk β€” a bug in the watchdog cannot regress search or schema.
+ - Pro: cleanly honors "reuse existing boundaries" since each slice extends exactly one.
+ - Con: duplicates atomic-write/fsync-rename logic across schema-mutate, watchdog auto-restore, and hook persistence (DRY violation).
+ - Con: duplicates audit-log + privacy-redaction logic (schema mutate-audit vs. hook capture vs. recovery events).
+ - Con: 4 tasks Γ— multiple sub-surfaces risks brushing the 10-theme ceiling with no consolidation lever.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Shared Atomic/Audit/Probe Spine
+- **Approach**: Extract the cross-cutting primitives the three write-heavy tasks share β€” an atomic `withMutation` (.tmp+fsync+rename), a file-level lock with stale/liveness detection, an ISO-week JSONL audit writer with redaction, and a health-probe/invariant harness β€” into a small internal substrate, then build schema mutation, session-hook capture, and the watchdog on top of it. CJK remains the deliberate outlier wired only into the search layer. The schema pack-lock and watchdog probe become two consumers of one locking/probe abstraction rather than parallel implementations.
+- **Trade-offs**:
+ - Pro: strongest DRY/SOLID alignment β€” one atomic-write boundary, one audit boundary, one probe harness reused 3Γ—.
+ - Pro: the watchdog's invariant checks can directly reuse the `brain_doctor` probe surface, and auto-restore reuses snapshot/rollback gates instead of reinventing them.
+ - Pro: consolidates theme count β€” "atomic mutation substrate" + "audit/probe substrate" absorb several sub-items.
+ - Con: highest upfront design coupling β€” the spine must satisfy schema, hooks, and watchdog simultaneously, raising the chance of an over-fitted abstraction.
+ - Con: a regression in the shared spine has blast radius across three features, hurting the isolation that Variant 1 buys cheaply.
+ - Con: sequencing pressure β€” the spine must land first, so partial-merge fallback is weaker.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 3: Risk-Tiered (Full Read/Foundation, Opt-In Writes)
+- **Approach**: Ship the low-risk and well-bounded paths in full β€” CJK tokenization (indexing + query, optionalDeps soft-fail) and the complete schema mutation surface (the explicitly-deferred remainder of t_cbf4967f, already ADR-gated) β€” while deliberately scoping the two architecturally-novel tasks down to their safe core: session "hooks" implemented as an eager capture adapter that reuses the existing import pipeline rather than a new synchronous hook runtime, and the watchdog implemented as detect-and-recommend (plan-only health probe emitting a remediation plan, auto-restore strictly opt-in/off-by-default). Riskier real-time and auto-recovery behavior is deferred to a follow-up.
+- **Trade-offs**:
+ - Pro: directly satisfies the hard constraints β€” auto-restore is never default, session import behavior is untouched, theme count stays low.
+ - Pro: front-loads the two tasks with the clearest specs (CJK has an upstream reference impl; schema mutation has an accepted ADR) and de-risks the two flagged "needs design" tasks.
+ - Pro: keeps each feature default-off/byte-compatible with minimal new always-on machinery.
+ - Con: tasks t_9eaebcad and t_8d8ec450 are only partially delivered β€” the "real-time" and "self-healing" headline value is deferred.
+ - Con: still some duplication of atomic-write/audit logic since no shared spine is extracted (mitigated by smaller write surface).
+ - Con: requires explicit operator agreement that two of four tasks ship reduced-scope.
+- **Complexity**: medium
+- **Risk**: low
+
+### Recommended: Variant 3
+**Rationale**: The two upstream-derived tasks (session hooks, watchdog) are both flagged "needs design" and carry the project's sharpest constraints β€” no default auto-restore, no break to session import β€” so reducing them to their safe, default-off core is the lowest-risk way to keep all four tasks in one PR under the 10-theme ceiling. It still delivers the two best-specified tasks (CJK with an upstream reference, schema mutation with an accepted ADR) at full scope, and the smaller write surface keeps the DRY cost of skipping Variant 2's shared spine modest while avoiding that spine's three-feature blast radius.
diff --git a/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/prompt.md b/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/prompt.md
new file mode 100644
index 00000000..f71d2aaa
--- /dev/null
+++ b/docs/brainstorm/cjk-schema-lifecycle-recovery/cli-output/prompt.md
@@ -0,0 +1,194 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+This is a multi-task Open Second Brain feature-release PR. The operator explicitly selected all four tasks for the same PR. The primary task is t_327f1876; the other three are additional required scope.
+
+## t_327f1876 - [upstream:agentmemory] CJK tokenizer for vault search
+
+**Source**: https://github.com/rohitg00/agentmemory/releases/tag/v0.9.13
+**Repo**: rohitg00/agentmemory (9500\*)
+**Released**: v0.9.13 (2026-05-15T09:15:55Z)
+
+### What
+
+agentmemory added CJK-aware BM25 tokenization: jieba for Chinese, tiny-segmenter for Japanese, rule-based syllable split for Korean. Mixed CJK+Latin runs preserve token order in a single pass. Segmenters are optionalDependencies so the base install stays lean.
+
+### Why useful for OSB
+
+OSB vault search uses FTS5 which does not segment CJK text - Chinese/Japanese/Korean content is indexed as individual Unicode codepoints rather than words, degrading recall and relevance. Porting the CJK segmentation approach (with the same soft-fail optionalDependencies pattern) would improve search quality for CJK vault content without bloating the default install.
+
+### Status in OSB
+
+- Verdict: not_in_osb_useful
+- Code hints: src/core/search/schema.ts (FTS5 chunk_fts table), src/core/search/index.ts (search pipeline entry)
+
+### Notes and comments
+
+agentmemory uses @node-rs/jieba (native, no model download) and tiny-segmenter (~25 KB pure JS). OSB already ships native Node addons via Bun, so jieba would fit the same pattern. The segmenter-optional pattern (soft-fail with one-time hint) is also worth copying.
+
+Also surfaced upstream in safishamsi/graphify v0.8.19. graphify uses jieba for Chinese query segmentation with character bigram fallback when jieba is not installed. Original compound tokens preserved alongside segments for exact-match. Corroborating signal: same CJK segmentation approach, different application (query-time vs indexing-time).
+
+Validator: clean, priority 2. Caveat: CJK segmentation pulls in segmenter deps and conflicts with the dependency-free, language-agnostic-by-construction core; needs an ADR on whether to break that invariant.
+
+## t_d6b5632b - [schema-packs] Schema mutation surface - primitives, pack-lock, MCP admin ops, CLI verbs, schema-author skill
+
+**Follow-up to**: t_cbf4967f (foundation slice shipped in PR #52 / v0.25.0). This task carries the deferred mutation/admin surface that the foundation ADR explicitly parked.
+
+**Builds on**: the runtime schema-packs foundation released in v0.25.0 - shared schema vocabulary (`src/core/brain/schema-vocab.ts`), `_brain.yaml schema:` parsing, inert `schema_type:` artifact metadata, and the read-only `o2b brain schema` report. ADR: `docs/brainstorm/runtime-schema-packs-foundation/adr.md`.
+
+### What (deferred scope, not yet implemented)
+
+The full "Schema Cathedral v3" surface from gbrain commit 3c1cc8a, on top of the now-shipped read-only foundation:
+
+1. Mutation primitives - the 11 ops (`add_type`, `remove_type`, `update_type`, `add_alias`, `remove_alias`, `add_prefix`, `remove_prefix`, `add_link_type`, `remove_link_type`, `set_extractable`, `set_expert_routing`), each wrapped in an atomic `withMutation` (.tmp + fsync + rename) with a pre-write lint-validation gate.
+2. Pack-lock - atomic file-level locking with stale detection (TTL + liveness probe) so concurrent writers cannot corrupt the schema.
+3. MCP admin ops - the 9 operations for remote agents: `get_active_schema_pack`, `list_schema_packs`, `schema_stats`, `schema_lint`, `schema_graph`, `schema_explain_type`, `schema_review_orphans` (read scope), `schema_apply_mutations` (admin scope, batched), `reload_schema_pack`.
+4. CLI verbs - the broader schema-management verb set beyond the read-only `o2b brain schema` report (stats with per-type counts / coverage / dead-prefix detection, chunked sync backfill, etc.).
+5. schema-author skill - the discoverable 7-phase agent workflow (brain -> assess -> propose -> apply -> sync -> verify -> commit).
+6. Mutate-audit - ISO-week JSONL audit log with privacy redaction.
+
+### Why
+
+The v0.25.0 foundation makes taxonomy declarable and inspectable but read-only. This task adds the safe write path so agents/operators can evolve the schema vocabulary at runtime with atomic guarantees, locking, and an audit trail - the production-grade authoring layer.
+
+### Constraints / sequencing
+
+- Gated by the foundation ADR; needs its own design pass before build.
+- Must reuse the single validation boundary (`schema-vocab.ts`) rather than introduce a parallel vocabulary.
+- Keep Markdown/YAML as the source of truth; mutations write through atomic file ops, no hidden registry DB.
+
+### Status in OSB
+
+- Verdict: foundation present (v0.25.0); mutation/admin surface absent.
+- This is the explicitly-deferred remainder of t_cbf4967f.
+
+## t_9eaebcad - [upstream:cavemem] Real-time session lifecycle hooks for memory capture
+
+**Source**: https://github.com/JuliusBrussee/cavemem/releases/tag/v0.1.0
+**Repo**: JuliusBrussee/cavemem (446\*)
+**Released**: v0.1.0 (2026-04-18T00:48:33Z)
+
+### What
+
+cavemem hooks fire synchronously at session boundaries (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) to capture observations and write them to local SQLite storage in real-time. Hook handlers complete in under 150ms. A local worker auto-spawns on first hook to build embeddings and self-exits when idle.
+
+### Why useful for OSB
+
+OSB imports sessions post-hoc by parsing JSONL and rollout files (`src/core/brain/sessions/import.ts:117 importSession`) after they have been written by the IDE. Real-time lifecycle hooks would allow OSB to capture observations as they happen, enabling immediate memory availability during active sessions rather than waiting for the next import cycle. Particularly valuable for MCP search tool path where agents query memory mid-session.
+
+### Status in OSB
+
+- Verdict: not_in_osb_useful
+- Code hints: `src/core/brain/sessions/import.ts`, `src/core/brain/sessions/claude.ts`, `src/core/brain/sessions/codex.ts`. No real-time hook system exists.
+
+### Notes and comments
+
+Five hook types map to natural OSB extension points: SessionStart (initialize context), UserPromptSubmit (capture intent), PostToolUse (capture tool outcomes), Stop/SessionEnd (finalize and compress). Auto-spawning worker pattern for embeddings could replace OSB current embedding strategy for session content.
+
+Validator: clean, priority 2. Caveat: real-time lifecycle hooks are an architectural shift from post-hoc batch import; needs design.
+
+## t_8d8ec450 - [upstream:TencentDB-Agent-Memory] Self-healing watchdog for brain gateway auto-recovery
+
+**Source**: https://github.com/Tencent/TencentDB-Agent-Memory/releases/tag/v0.3.3
+**Repo**: Tencent/TencentDB-Agent-Memory (3891\*)
+**Released**: v0.3.3 (2026-05-08)
+
+### What
+
+TencentDB Agent Memory Hermes plugin includes a watchdog + lazy probe mechanism that detects gateway anomalies and automatically recovers without human intervention. The watchdog monitors plugin health and triggers lazy probe on failures, restoring connectivity and state automatically.
+
+### Why useful for OSB
+
+OSB has brain snapshot/restore (`src/core/brain/snapshot.ts:597 restoreSnapshot`) and rollback CLI (`src/cli/brain/verbs/rollback.ts:12 cmdBrainRollback`) but no continuous health monitoring or auto-recovery. A watchdog would detect vault corruption, MCP server disconnects, or search index degradation and attempt automatic remediation before requiring user intervention. This would improve reliability for always-on agent sessions.
+
+### Status in OSB
+
+- Verdict: not_in_osb_useful
+- Code hints: `src/core/brain/snapshot.ts`, `src/cli/brain/verbs/rollback.ts`. Recovery is manual/CLI-driven, no background watchdog or health probe exists.
+
+### Notes and comments
+
+The watchdog pattern is lightweight - periodic health checks with exponential backoff retry. Could be implemented as a gateway background task that validates vault invariants (similar to brain_doctor) and triggers auto-restore from latest snapshot on critical failures.
+
+Validator: clean, priority 2. Caveat: background watchdog / auto-recovery needs design on triggers and safety before any auto-restore from snapshot.
+
+# Project context
+
+Project: Open Second Brain, TypeScript/Bun runtime, Obsidian-compatible Markdown vaults, CLI + MCP server surfaces.
+
+Recent commits:
+
+- f62918c feat: runtime schema packs foundation - schema vocabulary, artifact taxonomy, schema inspection (#52)
+- 14d1ee1 feat: brain model semantics foundation - typed preference relations, memory labels, dry-run backfill (#51)
+- 3a5d5c3 feat: agent capability CLI integration - runtime MCP capabilities, inherited JSON, completions (#50)
+- a085bfa feat: vault portability + session economy - codec, sources dashboard, vault-map tokens, multi-vault profiles, graph export/import (#49)
+- 73e4a28 feat: brain lifecycle suite - mutation audit, multi-phase dream, reconcile domains, morning brief, temporal extraction, heal enrichment (#48)
+- bd49cd5 feat: recall and ranking quality - Weibull recency, query intent, synonym expansion, recall budgets, query cache, pre-compress pack (#47)
+- cbbe18f feat: typed graph semantics - typed relations, visibility scoping, MCP landscape (#46)
+- 5fa7eb0 feat: MCP context economy - preview budget, artifact fetch, recall hint (#45)
+- 2bd3f48 v0.17.0 - Brain Lifecycle Review Suite (#44)
+- 9b87838 v0.16.0 - Agent boundary control surfaces (#43)
+- 66980b2 ci: drop bun version floor, track latest only (#42)
+- feca6a7 v0.15.0 - Cross-agent query foundation (#41)
+- ffde4ac chore(release): v0.14.1 (#40)
+- bc97b38 refactor: add validation toolchain and normalize project formatting (#39)
+- b76199a v0.14.0 - Semantic Brain Health and Self-Maintenance (#38)
+- 2147640 v0.13.0 - Hybrid Search and Recall Quality (#37)
+- 84886d1 v0.12.0 - Brain Integrity Suite (#36)
+- c002268 v0.11.0 - Brain-centric vault layout (#35)
+- a8d4803 v0.10.18 - temporal axis (#34)
+- d0598af v0.10.17 - link graph surfaces (#33)
+
+Related files:
+
+- `src/core/search/schema.ts`: FTS5 chunk_fts currently uses `tokenize='unicode61 remove_diacritics 2'`.
+- `src/core/search/indexer.ts`: chunk content is read, chunked, and persisted through `Store.replaceChunks`; content currently goes to FTS unchanged.
+- `src/core/search/search.ts`: query string goes directly into `runFtsQuery`; synonym/entity layers tokenize Latin-style terms only.
+- `src/core/search/store.ts`: single SQL boundary and existing proper-lockfile pattern for index writer locking.
+- `src/core/brain/schema-vocab.ts`: single validation boundary for built-in and `_brain.yaml schema:` vocabulary.
+- `src/core/brain/schema-report.ts`: current read-only schema report with usage/finding logic.
+- `src/cli/brain/verbs/schema.ts`: current `o2b brain schema [--json]` report command.
+- `src/mcp/tools.ts` and `src/mcp/brain-tools.ts`: current MCP registry slices and scopes.
+- `src/core/brain/sessions/import.ts`: post-hoc session import orchestrator writes signals via `writeSignal`.
+- `src/core/brain/sessions/registry.ts`: adapter registry for Claude/Codex/Hermes import formats.
+- `src/core/brain/snapshot.ts` and `src/cli/brain/verbs/rollback.ts`: manual snapshot extract/restore and rollback safety gate.
+- `docs/brainstorm/runtime-schema-packs-foundation/adr.md`: accepted ADR says future mutation primitives should edit `_brain.yaml` atomically and keep no second store.
+
+Conventions:
+
+- Plain Markdown and `_brain.yaml` remain the source of truth; no hidden service or registry DB.
+- New behavior should be default-off or byte-compatible when config is absent.
+- CLI commands should support stable `--json` output where useful.
+- MCP tools use a registry of `ToolDefinition` objects with scope filtering and small structured payloads.
+- Search uses SQLite FTS5 plus optional embeddings. Optional native deps are already accepted for `sqlite-vec`; missing optional dependencies must degrade cleanly.
+- Current package scripts: `bun run lint`, `bun run fmt`, `bun run fmt:check`, `bun run typecheck`, `bun run test`, `bun run sync-version:check`.
+- Active Brain preferences: no `Brain/active.md` exists in this repository workspace.
+
+Constraints:
+
+- Do not create a second schema registry DB.
+- Do not make auto-restore from snapshots the default; recovery must be explicit/safe or plan-only unless the operator opts in.
+- Do not break existing session import behavior.
+- Do not require CJK segmenter packages for base installs; use optionalDependencies and soft failure / deterministic fallback.
+- Keep changes SOLID/KISS/DRY and reuse existing boundaries.
+- The final PR may be large, but it must stay below 10 feature themes.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+### Recommended: Variant N
+
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/cjk-schema-lifecycle-recovery/design.md b/docs/brainstorm/cjk-schema-lifecycle-recovery/design.md
new file mode 100644
index 00000000..1f99485d
--- /dev/null
+++ b/docs/brainstorm/cjk-schema-lifecycle-recovery/design.md
@@ -0,0 +1,84 @@
+# CJK search, schema mutation, lifecycle capture, and recovery - shared reliability spine
+
+**Status:** draft
+**Author:** GitHub Copilot (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+Open Second Brain has four high-priority gaps that now need to ship together: CJK vault search quality, the deferred runtime schema-pack mutation/admin surface, real-time session lifecycle capture, and self-healing brain gateway recovery. The common risk is that three of the four tasks add new write paths around the Brain vault. The PR must deliver the full task scope while preserving the existing Markdown/YAML source of truth, default install ergonomics, and rollback safety guarantees.
+
+## Scope
+
+- CJK-aware FTS indexing and query tokenization for Chinese, Japanese, Korean, and mixed CJK/Latin text, with optional segmenter dependencies and deterministic fallback tokenization.
+- A shared internal reliability spine for atomic file replacement, stale-aware file locking, privacy-redacted ISO-week JSONL audit append, and reusable health probe result types.
+- Schema-pack mutation primitives for the 11 requested operations, writing only through `Brain/_brain.yaml` and reusing `schema-vocab.ts` for token validation.
+- Schema pack-lock, pre-write lint validation, schema mutation audit log, CLI management verbs, MCP admin/read tools, and a schema-author skill workflow.
+- Real-time session lifecycle hook capture for SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd, using the existing hook launcher and Brain write boundaries.
+- Brain watchdog probes, lazy remediation planning, opt-in recovery execution, exponential backoff metadata, and safe snapshot restore integration through the existing rollback/snapshot boundary.
+- User-facing docs, changelog, version bump, and tracker/kanban completion at release time.
+
+## Out of scope
+
+- A second schema registry database or generated schema-pack state outside `_brain.yaml`.
+- Making snapshot auto-restore implicit. Destructive recovery requires an explicit CLI/MCP option and must reuse rollback drift safeguards.
+- Replacing the existing post-hoc session import pipeline.
+- Cloud vector database storage, subagent orchestration, or provider backend abstraction.
+- Changing operational lifecycle enums such as preference status, retire state, or apply-evidence result semantics.
+
+## Chosen approach
+
+Use a small shared reliability spine for the new write-heavy surfaces, while keeping CJK search isolated inside the search subsystem. The spine owns only generic mechanics: atomic file writes, stale-aware locks, audit JSONL append with redaction, and normalized probe/remediation result shapes. Schema mutation, lifecycle capture, and watchdog recovery remain separate domain modules that depend on those primitives rather than sharing business logic.
+
+For CJK search, add an index-time/search-time tokenizer boundary that expands CJK runs into segment tokens while preserving the original text for exact matching and display. Optional segmenters improve Chinese/Japanese segmentation when installed; the default fallback still improves CJK recall without making base installs fail.
+
+## Design decisions
+
+- **CJK search uses an FTS-only shadow column.** Add a `chunks.fts_content` column and rebuild `chunk_fts` to index `fts_content` plus `heading_path`, while hydrated result snippets continue to read `chunks.content`. This avoids polluting displayed chunk text with token expansion.
+- **CJK query tokenization mirrors indexing.** `buildFtsMatch` receives tokenizer-expanded terms for CJK runs so unspaced queries can match the indexed segments. Mixed CJK/Latin order is preserved by walking Unicode runs once.
+- **Optional segmenters are isolated.** Dynamic loading lives in one module. Missing `@node-rs/jieba` or `tiny-segmenter` degrades to deterministic bigram/unigram fallback and can emit a one-time structured warning where callers expose warnings.
+- **Schema mutations edit `_brain.yaml` only.** The schema pack remains the `_brain.yaml schema:` block plus optional metadata under that block. No hidden registry DB, no generated active-pack file.
+- **Schema metadata is forward-compatible.** The existing array categories remain valid. Additional fields for aliases, prefixes, link types, extractable tokens, and expert routing are parsed and validated by new schema-pack helpers without breaking vaults that only use the v0.25.0 shape.
+- **Mutation ops are batched and prevalidated.** `schema_apply_mutations` and CLI apply perform all mutations against an in-memory candidate, run schema lint, and write atomically only if the batch is valid.
+- **Pack-lock uses the shared lock primitive.** Lock TTL and stale detection are configurable, but default to conservative values aligned with the existing proper-lockfile use in search indexing.
+- **MCP admin tools are full-scope only.** Read operations can appear on the normal full server; mutation runs through `schema_apply_mutations`, not writer-only scope, so narrow writer surfaces do not grow silently.
+- **Lifecycle hooks capture structured events, not speculative preferences.** Hook capture records lifecycle observations and extracts explicit `@osb` markers/tool feedback through the existing signal boundaries. It does not infer preferences from arbitrary prompts.
+- **Hook handlers stay fast and quiet.** They target sub-150ms local work in normal cases, never crash the host runtime, and enqueue/audit only small payloads.
+- **Watchdog recovery is opt-in for destructive actions.** Probe and recommendation are always safe. Search-index repair and hook/config reload can run automatically when requested. Snapshot restore requires an explicit restore mode and reuses rollback drift checks.
+
+## File changes
+
+Expected new files:
+
+- `src/core/reliability/atomic.ts`
+- `src/core/reliability/audit.ts`
+- `src/core/reliability/lock.ts`
+- `src/core/reliability/probe.ts`
+- `src/core/search/cjk-tokenizer.ts`
+- `src/core/brain/schema-pack.ts`
+- `src/core/brain/schema-mutate.ts`
+- `src/core/brain/schema-admin.ts`
+- `src/core/brain/session-lifecycle.ts`
+- `src/core/brain/watchdog.ts`
+- `src/cli/brain/verbs/session-hook.ts`
+- `src/cli/brain/verbs/watchdog.ts`
+- `hooks/session-capture.ts`
+- `skills/schema-author/SKILL.md`
+- focused tests under `tests/core/`, `tests/cli/`, `tests/mcp/`, and `tests/hooks/`
+
+Expected modified files:
+
+- Search schema/store/indexer/search/FTS modules and related tests.
+- Brain schema vocabulary/report/CLI/MCP registration and help/manifest files.
+- Brain session hook config and hook README.
+- Snapshot/rollback integration only through public helpers, not by changing rollback semantics.
+- README, docs, CHANGELOG, package metadata, and lockfile for optional dependencies/version bump.
+
+## Risks and open questions
+
+- CJK FTS migration must preserve existing indexes and make reindex guidance clear when old DBs lack `fts_content`.
+- Optional native segmenter availability may vary by platform. The fallback path must be test-covered and useful without native packages.
+- The schema metadata shape under `_brain.yaml schema:` is new; tests must lock compatibility with the existing simple-array foundation shape.
+- MCP tool count and scopes must remain explicit so admin mutation does not leak into writer-only runtime configurations.
+- Real-time hooks can duplicate post-hoc import if they process the same explicit marker later. Dedup hashes must be reused.
+- Watchdog remediation can become dangerous if it bypasses drift detection. Snapshot restore must call the same safety checks as rollback or require an explicit force flag.
diff --git a/docs/brainstorm/cjk-schema-lifecycle-recovery/plan.md b/docs/brainstorm/cjk-schema-lifecycle-recovery/plan.md
new file mode 100644
index 00000000..4e9c8df5
--- /dev/null
+++ b/docs/brainstorm/cjk-schema-lifecycle-recovery/plan.md
@@ -0,0 +1,65 @@
+# CJK search, schema mutation, lifecycle capture, and recovery - implementation plan
+
+## Tasks
+
+### Task 1: Shared reliability spine
+
+- **Files**: `src/core/reliability/atomic.ts`, `src/core/reliability/lock.ts`, `src/core/reliability/audit.ts`, `src/core/reliability/probe.ts`, `tests/core/reliability/*.test.ts`
+- **Acceptance**: Tests prove atomic replacement preserves old content on validation failure, stale locks are reported deterministically, redacted JSONL audit records are appended under ISO-week paths, and probe result helpers produce stable JSON.
+- **Depends on**: none
+
+### Task 2: CJK search tokenizer
+
+- **Files**: `src/core/search/cjk-tokenizer.ts`, `src/core/search/schema.ts`, `src/core/search/store.ts`, `src/core/search/indexer.ts`, `src/core/search/fts.ts`, `src/core/search/search.ts`, `tests/core/search/cjk-tokenizer.test.ts`, `tests/core/search.test.ts`, `package.json`, `bun.lock`
+- **Acceptance**: A failing test first demonstrates that unspaced CJK query text does not retrieve matching CJK content; implementation then passes with indexed `fts_content`, query tokenization, optional segmenter soft-fail fallback, and no display-content pollution.
+- **Depends on**: none
+
+### Task 3: Schema mutation core
+
+- **Files**: `src/core/brain/schema-vocab.ts`, `src/core/brain/types.ts`, `src/core/brain/policy.ts`, `src/core/brain/schema-pack.ts`, `src/core/brain/schema-mutate.ts`, `src/core/brain/schema-report.ts`, `tests/core/brain/schema-pack.test.ts`, `tests/core/brain/schema-mutate.test.ts`, `tests/core/brain/schema-report.test.ts`
+- **Acceptance**: Tests cover all 11 mutation primitives, batched prevalidation, atomic `_brain.yaml` writes, lock contention, schema lint findings, and audit log redaction without breaking existing simple-array schema config.
+- **Depends on**: Task 1
+
+### Task 4: Schema CLI and MCP admin surface
+
+- **Files**: `src/cli/brain/verbs/schema.ts`, `src/cli/brain/help-text.ts`, `src/cli/command-manifest.ts`, `src/mcp/schema-tools.ts`, `src/mcp/tools.ts`, `tests/cli/brain-schema-cli.test.ts`, `tests/mcp/schema-tools.test.ts`, `skills/schema-author/SKILL.md`
+- **Acceptance**: CLI tests cover `stats`, `lint`, `graph`, `explain`, `orphans`, `apply`, `sync`, and JSON output. MCP tests cover the 9 requested tools: `get_active_schema_pack`, `list_schema_packs`, `schema_stats`, `schema_lint`, `schema_graph`, `schema_explain_type`, `schema_review_orphans`, `schema_apply_mutations`, and `reload_schema_pack`.
+- **Depends on**: Task 3
+
+### Task 5: Real-time session lifecycle capture
+
+- **Files**: `src/core/brain/session-lifecycle.ts`, `src/cli/brain/verbs/session-hook.ts`, `src/cli/brain.ts`, `src/cli/brain/help-text.ts`, `src/cli/command-manifest.ts`, `hooks/session-capture.ts`, `hooks/hooks.json`, `hooks/README.md`, `tests/core/brain/session-lifecycle.test.ts`, `tests/cli/brain-session-hook.test.ts`, `tests/hooks/session-capture.test.ts`
+- **Acceptance**: Tests cover SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd payloads; explicit markers/tool feedback write immediately through existing signal/dedup boundaries; lifecycle observations audit/log without crashing malformed hook payloads.
+- **Depends on**: Task 1
+
+### Task 6: Brain watchdog and safe recovery
+
+- **Files**: `src/core/brain/watchdog.ts`, `src/cli/brain/verbs/watchdog.ts`, `src/cli/brain.ts`, `src/cli/brain/help-text.ts`, `src/cli/command-manifest.ts`, `src/mcp/brain-tools.ts` or `src/mcp/watchdog-tools.ts`, `tests/core/brain/watchdog.test.ts`, `tests/cli/brain-watchdog.test.ts`, `tests/mcp/watchdog-tools.test.ts`
+- **Acceptance**: Tests cover healthy probes, degraded probes, lazy remediation plans, search-index repair recommendation, explicit recovery execution, exponential backoff metadata, audit output, and snapshot restore refusal unless explicit restore/force options are provided.
+- **Depends on**: Task 1
+
+### Task 7: Documentation, changelog, version, and release prep
+
+- **Files**: `README.md`, `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/mcp.md`, `CHANGELOG.md`, `package.json`, synced version files
+- **Acceptance**: Docs describe the new CJK search behavior, schema authoring/admin surface, lifecycle capture hooks, and watchdog safety model. `bun run sync-version:check` passes after the required version bump.
+- **Depends on**: Tasks 2-6
+
+## TDD order
+
+1. Task 1 reliability spine tests, implementation, focused test run.
+2. Task 2 CJK search failing test, implementation, focused search test run.
+3. Task 3 schema mutation failing tests, implementation, focused schema test run.
+4. Task 4 CLI/MCP failing tests, implementation, focused CLI/MCP test run.
+5. Task 5 lifecycle hook failing tests, implementation, focused hook/session test run.
+6. Task 6 watchdog failing tests, implementation, focused watchdog test run.
+7. Task 7 docs/version update, then full QA.
+
+## Commit plan
+
+- `chore(brainstorm): cjk-schema-lifecycle-recovery`
+- `feat(core): add shared reliability primitives`
+- `feat(search): add cjk-aware vault search tokenization`
+- `feat(schema): add schema mutation and admin surface`
+- `feat(brain): capture session lifecycle hooks`
+- `feat(brain): add watchdog recovery probes`
+- `docs: document cjk schema lifecycle recovery release`
diff --git a/docs/brainstorm/cjk-schema-lifecycle-recovery/variants.md b/docs/brainstorm/cjk-schema-lifecycle-recovery/variants.md
new file mode 100644
index 00000000..8834a22e
--- /dev/null
+++ b/docs/brainstorm/cjk-schema-lifecycle-recovery/variants.md
@@ -0,0 +1,52 @@
+# CJK search, schema mutation, lifecycle capture, and recovery - variants
+
+## Consultant output
+
+### Variant 1: Four Isolated Vertical Slices
+
+- **Approach**: Treat each task as a self-contained module that touches only its own existing boundary - CJK at `search/schema.ts`+`indexer.ts`, schema mutation at `schema-vocab.ts`+a new `schema-mutate.ts`, session hooks as a new `sessions/hooks.ts` adapter feeding `writeSignal`, watchdog as a standalone gateway background task. Each ships behind its own default-off config key with no shared scaffolding between them. The PR is the sum of four independently reviewable diffs.
+- **Trade-offs**:
+ - Pro: maximum reviewability and rollback granularity; each slice can be reverted without touching the others.
+ - Pro: lowest coupling risk - a bug in the watchdog cannot regress search or schema.
+ - Pro: cleanly honors "reuse existing boundaries" since each slice extends exactly one.
+ - Con: duplicates atomic-write/fsync-rename logic across schema-mutate, watchdog auto-restore, and hook persistence (DRY violation).
+ - Con: duplicates audit-log + privacy-redaction logic (schema mutate-audit vs. hook capture vs. recovery events).
+ - Con: 4 tasks x multiple sub-surfaces risks brushing the 10-theme ceiling with no consolidation lever.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Shared Atomic/Audit/Probe Spine
+
+- **Approach**: Extract the cross-cutting primitives the three write-heavy tasks share - an atomic `withMutation` (.tmp+fsync+rename), a file-level lock with stale/liveness detection, an ISO-week JSONL audit writer with redaction, and a health-probe/invariant harness - into a small internal substrate, then build schema mutation, session-hook capture, and the watchdog on top of it. CJK remains the deliberate outlier wired only into the search layer. The schema pack-lock and watchdog probe become two consumers of one locking/probe abstraction rather than parallel implementations.
+- **Trade-offs**:
+ - Pro: strongest DRY/SOLID alignment - one atomic-write boundary, one audit boundary, one probe harness reused 3x.
+ - Pro: the watchdog's invariant checks can directly reuse the `brain_doctor` probe surface, and auto-restore reuses snapshot/rollback gates instead of reinventing them.
+ - Pro: consolidates theme count - "atomic mutation substrate" + "audit/probe substrate" absorb several sub-items.
+ - Con: highest upfront design coupling - the spine must satisfy schema, hooks, and watchdog simultaneously, raising the chance of an over-fitted abstraction.
+ - Con: a regression in the shared spine has blast radius across three features, hurting the isolation that Variant 1 buys cheaply.
+ - Con: sequencing pressure - the spine must land first, so partial-merge fallback is weaker.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 3: Risk-Tiered (Full Read/Foundation, Opt-In Writes)
+
+- **Approach**: Ship the low-risk and well-bounded paths in full - CJK tokenization (indexing + query, optionalDeps soft-fail) and the complete schema mutation surface (the explicitly-deferred remainder of t_cbf4967f, already ADR-gated) - while deliberately scoping the two architecturally-novel tasks down to their safe core: session "hooks" implemented as an eager capture adapter that reuses the existing import pipeline rather than a new synchronous hook runtime, and the watchdog implemented as detect-and-recommend (plan-only health probe emitting a remediation plan, auto-restore strictly opt-in/off-by-default). Riskier real-time and auto-recovery behavior is deferred to a follow-up.
+- **Trade-offs**:
+ - Pro: directly satisfies the hard constraints - auto-restore is never default, session import behavior is untouched, theme count stays low.
+ - Pro: front-loads the two tasks with the clearest specs (CJK has an upstream reference impl; schema mutation has an accepted ADR) and de-risks the two flagged "needs design" tasks.
+ - Pro: keeps each feature default-off/byte-compatible with minimal new always-on machinery.
+ - Con: tasks t_9eaebcad and t_8d8ec450 are only partially delivered - the "real-time" and "self-healing" headline value is deferred.
+ - Con: still some duplication of atomic-write/audit logic since no shared spine is extracted (mitigated by smaller write surface).
+ - Con: requires explicit operator agreement that two of four tasks ship reduced-scope.
+- **Complexity**: medium
+- **Risk**: low
+
+### Recommended: Variant 3
+
+**Rationale**: The two upstream-derived tasks (session hooks, watchdog) are both flagged "needs design" and carry the project's sharpest constraints - no default auto-restore, no break to session import - so reducing them to their safe, default-off core is the lowest-risk way to keep all four tasks in one PR under the 10-theme ceiling. It still delivers the two best-specified tasks (CJK with an upstream reference, schema mutation with an accepted ADR) at full scope, and the smaller write surface keeps the DRY cost of skipping Variant 2's shared spine modest while avoiding that spine's three-feature blast radius.
+
+## Orchestrator decision
+
+Chosen: **Variant 2: Shared Atomic/Audit/Probe Spine**.
+
+The consultant's recommended Variant 3 is technically safer, but it conflicts with the operator's explicit instruction that `t_327f1876`, `t_d6b5632b`, `t_9eaebcad`, and `t_8d8ec450` all ship in full in this PR. Variant 2 is the best fit for that constraint because it keeps the broad scope cohesive: schema mutation, lifecycle capture, and watchdog recovery all share one atomic/audit/probe substrate instead of growing three parallel write paths. The main guardrail is to keep the shared substrate small and boring: atomic file replacement, lock acquisition, JSONL audit append, and probe result types only.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index ed494b85..a2b119bd 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -55,7 +55,8 @@ o2b brain audit Render a preference's full mutation audit trail (s
o2b brain morning-brief Read-only session-start summary (since v0.21.0): top confirmed preferences, recent reconcile open questions, recent notes; bounded by --max-chars-per-memory / --max-total-chars; --top-k / --lookback-days
o2b brain codec Deterministic lossless session codec (since v0.22.0): --compress | --expand over stdin or --in <file>; structured content preserved byte-for-byte
o2b brain sources Read-only dashboard of signals by (agent, source_type) (since v0.22.0): active/processed + distinct-topic counts; --json
-o2b brain schema Read-only runtime schema report (since v0.25.0): resolved vocabulary, artifact schema_type usage, unknown tokens, unused declarations; --json
+o2b brain schema Runtime schema report/admin (since v0.26.0): report|stats|lint|graph|explain|orphans|apply|sync; mutation writes are locked and audited
+o2b brain watchdog Probe Brain config/dirs/search index and plan safe recovery (since v0.26.0): --remediate [--dry-run], --restore <run_id> [--force-restore], --json
o2b brain graph-export Serialise the vault knowledge graph (pages, wikilinks, typed relations) to a stable graph.json (since v0.22.0): stdout or --out <file>
o2b brain graph-import Reconstruct vault page stubs from a graph.json (since v0.22.0): --mode skip|overwrite|merge; vault-guarded writes
o2b brain backlinks List inbound references to a Brain artifact id
@@ -63,6 +64,7 @@ o2b brain semantics-backfill Dry-run typed preference-edge backfill preview (si
o2b brain mcp-landscape List MCP servers configured across the vault (since v0.19.0): name, source file, packages, required env-var names (values never read)
o2b brain scan-inline Capture `@osb` markers from folders listed under `notes.read_paths` in _brain.yaml
o2b brain import-session Replay signals from a registered agent session .jsonl (or directory)
+o2b brain session-hook Internal hook bridge: read one lifecycle payload from stdin, capture prompt markers / brain_feedback, append lifecycle audit/log rows
o2b brain import-claude-memory (CLI-only) Import metadata.type=feedback entries from a Claude Code memory directory into Brain/preferences/. --dry-run / --apply, sidecar manifest for idempotency, UPDATE preserves accumulated evidence
```
@@ -138,8 +140,9 @@ o2b search "<query>" Hybrid full-text + semantic search across the vaul
filters on frontmatter scalars (post-FTS phase)
--verbose adds per-result why_retrieved reasons
--json for structured output (includes reasons[])
+ CJK text is expanded for FTS recall without polluting returned content
o2b search reindex Rebuild the SQLite + FTS5 index from scratch
- (required after upgrading to the v0.13.0 schema)
+ (required after upgrading to v0.13.0 recall schema or v0.26.0 CJK FTS content)
```
The fused ranking is sharpened by a recall-quality suite (v0.13.0), each
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index d8bcf99d..8eedfedd 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -192,13 +192,22 @@ Two important properties of this flow:
## Capture surfaces
-Three independent paths land a signal in `Brain/inbox/`:
+Four independent paths land a signal in `Brain/inbox/`:
- **Live** - the agent calls `brain_feedback` (MCP) or `o2b brain feedback` (CLI) the moment the rule is formulated. This is the path the end-to-end sequence above documents.
- **Inline** - the user (or agent) writes an `@osb` marker into any vault Markdown file. `o2b brain scan-inline` finds every marker, creates the corresponding signal, and annotates the source file with `@osbβœ“ [[sig-...]]` so a re-run is a no-op. Two marker shapes: a single line `@osb feedback negative topic=... principle="..."` or a fenced ` ```osb` block with YAML inside.
- **Session import** - `o2b brain import-session <path>` reads a Claude Code / Codex CLI / Hermes session JSONL and extracts both `@osb` markers from message text and replays of `brain_feedback` tool-use calls. Useful when MCP was not available at recording time or the agent did not make the call live.
+- **Lifecycle hook** - Claude Code / Codex hooks call `o2b brain session-hook` through `hooks/session-capture.ts`. `UserPromptSubmit` prompt markers and `PostToolUse` `brain_feedback` inputs are captured immediately through the same signal dedup hash, while SessionStart / Stop / SessionEnd / PostCompact observations append non-blocking lifecycle audit/log rows.
-All three paths share a normalised payload hash so the same rule captured twice from different surfaces dedups automatically. Pinned preferences are exempt from automatic retire (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`); only `o2b brain reject` can retire them.
+All four paths share a normalised payload hash so the same rule captured twice from different surfaces dedups automatically. Pinned preferences are exempt from automatic retire (`stale-no-evidence`, `expired-unconfirmed`, `rebutted`); only `o2b brain reject` can retire them.
+
+`o2b brain watchdog` is the recovery surface for this layout. It checks the
+Brain config, required directories, and rebuildable search index, emits
+exponential backoff metadata for schedulers, and writes an audit record. By
+default it only reports a remediation plan; `--remediate` may create missing
+Brain directories, but search repair remains a recommendation (`o2b search reindex`)
+and snapshot restore is refused unless `--restore <run_id>` and `--force-restore`
+are both explicit.
### Cross-project setup
@@ -286,14 +295,15 @@ Key rules baked into the pipeline:
The same pipeline is named as five explicit ordered phases - **close**
(scan) -> **reconcile** (contradictions) -> **synthesize** (promote /
confirm) -> **heal** (auto-retire stale, optional enrichment) -> **log**
+
- each emitting a workrun checkpoint and a structured entry in
-`DreamRunSummary.phases`. The internals are unchanged; the phases are
-labels over the existing seams, so every invariant above still holds.
+ `DreamRunSummary.phases`. The internals are unchanged; the phases are
+ labels over the existing seams, so every invariant above still holds.
- **Reconcile classification.** Each contradiction is bucketed by
structural signal shape (claims / entity / decisions / source-freshness).
Only source-freshness with a decisive recency gap auto-resolves - and
- even then it is *recorded* as a `reconcile` log event, never a
+ even then it is _recorded_ as a `reconcile` log event, never a
sub-threshold state mutation. Everything else surfaces in
`open_questions` for operator review rather than being force-merged.
- **Per-preference audit.** Every mutation (create / promote / update /
@@ -315,7 +325,7 @@ A `portability/` subsystem of deterministic primitives, all opt-in or
no-op by default:
- **Session codec.** A pure lossless `compress`/`expand` (`expand(compress(x))
- === x` for all input). Token savings come from reversibly collapsing
+=== x` for all input). Token savings come from reversibly collapsing
whitespace/blank-line runs behind a Private-Use-Area marker; code and
structured tokens are preserved byte-for-byte. Opt-in on the signal
store (gated by a `_raw_codec` marker the reader keys off) and exposed as
diff --git a/docs/mcp.md b/docs/mcp.md
index f0610d5e..df62572a 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -18,10 +18,10 @@ in Open Second Brain depends on the MCP server being running.
## Tool Highlights
-The full server currently advertises 47 tools. The table below highlights the
-operator-facing core, agent-source, health, and Pay Memory tools; the full
-surface also includes Brain writer, review, query, temporal, link-graph, and
-search tools. In Claude Code, that full schema can push MCP definitions beyond
+The full server currently advertises 57 tools. The table below highlights the
+operator-facing core, schema, agent-source, health, recovery, and Pay Memory
+tools; the full surface also includes Brain writer, review, query, temporal,
+link-graph, and search tools. In Claude Code, that full schema can push MCP definitions beyond
10% of the context window, causing `MCPSearch` tool-search deferral; use the
writer split below for the always-loaded writer subset, or the runtime
capability flags for a narrower per-process full server.
@@ -39,6 +39,16 @@ capability flags for a narrower per-process full server.
| `brain_audit` | Read-only per-preference mutation trail (create / promote / update / retire / merge) with agent, reason, revision + content-hash before/after. | `pref_id` |
| `brain_morning_brief` | Read-only session-start summary: top confirmed preferences, recent reconcile open questions, recent notes; character-budgeted. | β€” |
| `brain_sources` | Read-only dashboard of signals grouped by (agent, source_type) with active/processed and distinct-topic counts. | β€” |
+| `get_active_schema_pack` | Return the active runtime schema pack resolved from `Brain/_brain.yaml`. | β€” |
+| `list_schema_packs` | List schema packs available to the vault/runtime. | β€” |
+| `schema_stats` | Summarise declared schema tokens and observed artifact usage. | β€” |
+| `schema_lint` | Report unknown, unused, and invalid schema references without writing. | β€” |
+| `schema_graph` | Return a schema relationship graph for declared types, aliases, prefixes, and link types. | β€” |
+| `schema_explain_type` | Explain one schema token, including aliases, references, and usage. | `token` |
+| `schema_review_orphans` | Review declared schema tokens that have no observed usage. | β€” |
+| `schema_apply_mutations` | Apply audited, locked schema mutations to `Brain/_brain.yaml`. | `mutations` |
+| `reload_schema_pack` | Reload and validate the active schema pack after local edits. | β€” |
+| `brain_watchdog` | Probe Brain config, required dirs, and search-index health; optionally apply safe directory remediation. | β€” |
| `brain_switch_vault` | Activate a named vault profile; the change takes effect on the next server launch. | `name` |
| `payment_memory_init` | Bootstrap `Brain/payments/{policies,assets,drafts,reports}/ (+ dated YYYY-MM-DD receipt subdirs)` and write the spending policy template. | β€” |
| `payment_receipt_append` | Save a Markdown receipt for one paid API call. `raw_output` is redacted before persisting. | `service`, `status`, `reason` |
@@ -293,7 +303,7 @@ server to your Codex MCP config the same way as Hermes.
The plugin's `.mcp.json` ships **two** MCP-server entries:
-- `open-second-brain` - the full surface (46 tools, including `brain_health`, `brain_mcp_landscape`, `brain_agent_query`, `brain_agent_diff`, `brain_pinned_context`, `brain_pre_compress_pack`, `brain_audit`, `brain_morning_brief`, `brain_sources`, and `brain_switch_vault`); subject to Claude Code's `MCPSearch` tool-search deferral when MCP definitions push the system prompt past 10% of the context window.
+- `open-second-brain` - the full surface (57 tools, including `brain_health`, `brain_mcp_landscape`, `brain_agent_query`, `brain_agent_diff`, `brain_pinned_context`, `brain_pre_compress_pack`, `brain_audit`, `brain_morning_brief`, `brain_sources`, and `brain_switch_vault`); subject to Claude Code's `MCPSearch` tool-search deferral when MCP definitions push the system prompt past 10% of the context window.
- `open-second-brain-writer` - a minimal always-loaded surface of five tools: `brain_feedback`, `brain_apply_evidence`, `brain_note`, `brain_pinned_context` (writers) and `brain_context` (read-only pull-bootstrap of `Brain/active.md` plus pinned context, v0.16.0). The agent records taste signals, evidence events, milestone notes, and current-task pinned facts - and fetches the active rule digest at session start in runtimes without a SessionStart hook - without a ToolSearch round-trip on every session boot.
Both servers reuse the same backing CLI (`o2b mcp --scope writer` vs the default `--scope full`). Handlers are byte-identical; the writer-mode instructions text explicitly tells the agent to prefer the writer copy over any duplicate the full server still exposes (both call the same code path).
diff --git a/hooks/README.md b/hooks/README.md
index a54a5482..ffba8f05 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -18,10 +18,15 @@ hook payload shape, not on the runtime.
## What the hooks do
-| Event | Matcher | Behaviour |
-|---------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
-| `PostToolUse` | `Write\|Edit\|MultiEdit\|apply_patch` | Emits `additionalContext` pointing at the three Brain writer tools (`brain_feedback`, `brain_apply_evidence`, `brain_note`) for a durable edit. |
-| `Stop` | (every Stop) | If the turn produced a durable artifact and none of `brain_feedback` / `brain_apply_evidence` / `brain_note` landed, returns `decision: "block"` once, then lets the second Stop pass. |
+| Event | Matcher | Behaviour |
+| ------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SessionStart` | `startup\|resume\|clear` | Injects `Brain/active.md` and records a non-blocking `session-lifecycle` observation. |
+| `UserPromptSubmit` | `*` | Captures explicit `@osb feedback ...` markers from the submitted prompt immediately through the signal/dedup boundary. |
+| `PostToolUse` | `brain_feedback` | Replays successful `brain_feedback` tool input immediately through the same signal/dedup boundary. |
+| `PostToolUse` | `Write\|Edit\|MultiEdit\|apply_patch` | Emits `additionalContext` pointing at the three Brain writer tools (`brain_feedback`, `brain_apply_evidence`, `brain_note`) for a durable edit. |
+| `PostCompact` | `manual\|auto` | Re-injects `Brain/active.md` and records a post-compact lifecycle observation. |
+| `Stop` | (every Stop) | If the turn produced a durable artifact and none of `brain_feedback` / `brain_apply_evidence` / `brain_note` landed, returns `decision: "block"` once, then lets the second Stop pass. |
+| `SessionEnd` | `*` | Records a non-blocking lifecycle observation for session close. |
The Stop guardrail respects the runtime-provided `stop_hook_active`
flag: it fires at most once per turn, so the agent can deliberately
@@ -69,6 +74,11 @@ call would.
Codex ever switches to a "ship subtree only" extraction model, the
symlink will dangle and the hooks tree will need to move
physically under `plugins/codex/hooks/` (or be duplicated).
+
+- `session-capture.ts` β€” Bun entry script that handles lifecycle
+ observations and immediate marker/tool-feedback capture. It emits
+ no stdout to the runtime; writes go to Brain signals plus
+ `session-lifecycle` audit/log rows.
- `post-write-reminder.ts` / `stop-log-guardrail.ts` β€” Bun entry
scripts. They are tiny by design: they parse stdin, query
`lib/transcript.ts` and `lib/detect.ts`, and emit the hook's JSON
@@ -77,8 +87,8 @@ call would.
stdin.
- `lib/transcript.ts` β€” JSONL parser that recognises both the
Claude Code shape (top-level `{type:"user"|"assistant", message:
- {content:[...]}}`) and the Codex shape (`{type:"response_item",
- payload:{type:"function_call"|"custom_tool_call", name}}`).
+{content:[...]}}`) and the Codex shape (`{type:"response_item",
+payload:{type:"function_call"|"custom_tool_call", name}}`).
- `lib/detect.ts` β€” canonical lists of artifact / log tool names.
- `lib/messages.ts` β€” reminder + block text. Kept here so it can be
unit-tested without a hook subprocess.
diff --git a/hooks/hooks.json b/hooks/hooks.json
index f0fe2496..e1488500 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -1,6 +1,17 @@
{
"hooks": {
"PostToolUse": [
+ {
+ "matcher": "brain_feedback",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing brain_feedback lifecycle event"
+ }
+ ]
+ },
{
"matcher": "Write|Edit|MultiEdit|apply_patch",
"hooks": [
@@ -22,6 +33,57 @@
"command": "o2b-hook active-inject",
"timeout": 10,
"statusMessage": "OSB: injecting active preferences"
+ },
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing session start"
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "matcher": "*",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing prompt markers"
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "matcher": "*",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing session stop"
+ },
+ {
+ "type": "command",
+ "command": "o2b-hook stop-log-guardrail",
+ "timeout": 10,
+ "statusMessage": "OSB: checking stop log guardrail"
+ }
+ ]
+ }
+ ],
+ "SessionEnd": [
+ {
+ "matcher": "*",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing session end"
}
]
}
@@ -35,6 +97,12 @@
"command": "o2b-hook active-inject",
"timeout": 10,
"statusMessage": "OSB: re-injecting active preferences after compact"
+ },
+ {
+ "type": "command",
+ "command": "o2b-hook session-capture",
+ "timeout": 10,
+ "statusMessage": "OSB: capturing post-compact lifecycle event"
}
]
}
diff --git a/hooks/session-capture.ts b/hooks/session-capture.ts
new file mode 100644
index 00000000..7bd633d9
--- /dev/null
+++ b/hooks/session-capture.ts
@@ -0,0 +1,28 @@
+#!/usr/bin/env -S bun
+/**
+ * Runtime lifecycle hook: capture prompt/tool/session observations into
+ * Brain without writing hook output back to the runtime. Failures are
+ * intentionally silent so a hook problem never blocks the agent.
+ */
+
+import { resolveAgentName, resolveVault } from "../src/core/config.ts";
+import { captureSessionLifecycleEvent } from "../src/core/brain/session-lifecycle.ts";
+import { readHookInput } from "./lib/stdin.ts";
+
+async function main(): Promise<void> {
+ const vault = resolveVault();
+ if (vault === null) return;
+ let payload: unknown;
+ try {
+ payload = await readHookInput();
+ } catch {
+ payload = null;
+ }
+ await captureSessionLifecycleEvent(vault, payload, {
+ agent: resolveAgentName(),
+ });
+}
+
+main().catch(() => {
+ // Never block the runtime on lifecycle capture failures.
+});
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 462f6c0d..9fc566eb 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.25.0",
+ "version": "0.26.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index ba355c1e..621cf5e5 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.25.0",
+ "version": "0.26.0",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
@@ -58,7 +58,9 @@
"typescript": "^5.5.0"
},
"optionalDependencies": {
- "sqlite-vec": "^0.1.9"
+ "@node-rs/jieba": "^2.0.1",
+ "sqlite-vec": "^0.1.9",
+ "tiny-segmenter": "^0.2.0"
},
"openclaw": {
"extensions": [
diff --git a/plugin.yaml b/plugin.yaml
index dd4c6f0c..11b7e293 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.25.0"
+version: "0.26.0"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index f40e2072..f53c82ff 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.25.0",
+ "version": "0.26.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.yaml
index 7699595a..4427db36 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.25.0"
+version: "0.26.0"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index 015d53db..13fb1424 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.25.0"
+version = "0.26.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/schema-author/SKILL.md b/skills/schema-author/SKILL.md
new file mode 100644
index 00000000..b9384e0a
--- /dev/null
+++ b/skills/schema-author/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: schema-author
+description: Use when adding, renaming, reviewing, or explaining Brain schema tokens, aliases, prefixes, link types, extractability, or expert routing in Open Second Brain vaults.
+---
+
+# Schema Author
+
+Use this skill when a task changes the active Brain schema pack in `Brain/_brain.yaml` or reviews content against that schema.
+
+## Workflow
+
+1. Inspect the active schema pack with `get_active_schema_pack` or `o2b brain schema --json`.
+2. Check current usage and findings with `schema_stats`, `schema_lint`, and `schema_review_orphans`.
+3. Explain candidate tokens with `schema_explain_type` before renaming or deleting them.
+4. Apply schema changes only through `schema_apply_mutations` or `o2b brain schema apply --mutation ...` so writes are locked, atomic, and audited.
+5. Re-run lint/stats after mutation and report changed tokens plus any remaining findings.
+
+## Mutation Notes
+
+Supported operations are `add_type`, `remove_type`, `update_type`, `add_alias`, `remove_alias`, `add_prefix`, `remove_prefix`, `add_link_type`, `remove_link_type`, `set_extractable`, and `set_expert_routing`.
+
+Schema tokens must be lowercase normalized tokens accepted by Open Second Brain schema validation. Prefer small, durable tokens over project-specific phrasing unless the schema pack is explicitly project-scoped.
diff --git a/src/cli/brain.ts b/src/cli/brain.ts
index d8a8db8b..db4c3f4c 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -29,6 +29,7 @@ import {
cmdBrainUnprotect,
cmdBrainRollback,
cmdBrainDoctor,
+ cmdBrainWatchdog,
cmdBrainHealth,
cmdBrainHistory,
cmdBrainAudit,
@@ -48,6 +49,7 @@ import {
handleBrainSnapshotSubcommand,
cmdBrainScanInline,
cmdBrainImportSession,
+ cmdBrainSessionHook,
cmdBrainImportClaudeMemory,
cmdBrainPageDedup,
cmdBrainTokenFootprint,
@@ -65,9 +67,7 @@ import {
cmdBrainWeekly,
} from "./brain/verbs/index.ts";
-export async function handleBrainSubcommand(
- argv: ReadonlyArray<string>,
-): Promise<number> {
+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;
@@ -129,6 +129,8 @@ export async function handleBrainSubcommand(
return await cmdBrainRollback(rest);
case "doctor":
return await cmdBrainDoctor(rest);
+ case "watchdog":
+ return await cmdBrainWatchdog(rest);
case "health":
return await cmdBrainHealth(rest);
case "history":
@@ -157,6 +159,8 @@ export async function handleBrainSubcommand(
return await cmdBrainScanInline(rest);
case "import-session":
return await cmdBrainImportSession(rest);
+ case "session-hook":
+ return await cmdBrainSessionHook(rest);
case "import-claude-memory":
return await cmdBrainImportClaudeMemory(rest);
case "merge":
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index b2a710da..e7e6f1b8 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -36,6 +36,7 @@ Brain verbs (observing memory):
rollback Restore Brain/ from a snapshot (--list or <run_id>; --yes;
--dry-run previews via the same diff renderer)
doctor Validate Brain invariants (--strict; --remediate [--dry-run])
+ watchdog Probe Brain health and plan safe recovery (--remediate, --restore, --force-restore)
health Semantic-health report: contradictions, concept gaps, stale claims
history Render a preference's edit-history timeline
audit Render a preference's full mutation audit trail
@@ -50,6 +51,7 @@ Brain verbs (observing memory):
mcp-landscape List MCP servers configured across the vault (packages, env names)
scan-inline Capture @osb markers from folders listed under notes.read_paths in _brain.yaml
import-session Replay signals from a registered agent session .jsonl (or directory)
+ session-hook Capture one runtime hook payload from stdin (internal hook bridge)
import-claude-memory Import metadata.type:feedback MEMORY entries as confirmed preferences
page-dedup Detect (and optionally merge) near-duplicate vault pages
token-footprint Report per-category vault token size with a warn threshold
@@ -164,6 +166,11 @@ export const VERB_HELP: Record<string, string> = {
"Validate invariants. Warnings exit 0 (or 2 with --strict). Errors always exit 1.\n" +
"--remediate builds a dependency-ordered repair plan and applies the\n" +
"auto-safe steps (content-hash re-stamp); --dry-run previews without writing.\n",
+ watchdog:
+ "usage: o2b brain watchdog [--vault <path>] [--json] [--remediate [--dry-run]]\n" +
+ " [--restore <run_id> [--force-restore]] [--attempt <n>]\n" +
+ "Probe Brain config/dirs/search index, emit recovery recommendations, and apply only explicit safe repairs.\n" +
+ "Snapshot restore is refused unless --restore and --force-restore are both explicit; use rollback for execution.\n",
health:
"usage: o2b brain health [--vault <path>] [--json]\n" +
"Semantic-health report: contradictory confirmed preferences, recurring\n" +
@@ -193,9 +200,12 @@ export const VERB_HELP: Record<string, string> = {
"Read-only dashboard of the brain's signals grouped by (agent, source_type)\n" +
"with active/processed and distinct-topic counts.\n",
schema:
- "usage: o2b brain schema [--vault <path>] [--json]\n" +
- "Read-only report of the resolved runtime schema vocabulary, artifact\n" +
- "schema_type usage counts, and unknown/unused taxonomy findings.\n",
+ "usage: o2b brain schema [report|stats|lint|graph|explain|orphans|apply|sync] [--vault <path>] [--json]\n" +
+ "Inspect and mutate the active runtime schema vocabulary through locked, audited writes.\n",
+ "session-hook":
+ "usage: o2b brain session-hook [--vault <path>] [--agent <name>] [--dry-run] [--json]\n" +
+ "Read one runtime hook JSON payload from stdin, capture inline @osb markers / brain_feedback tool calls,\n" +
+ "and append a non-blocking session-lifecycle audit/log observation. Intended for hooks/session-capture.ts.\n",
"graph-export":
"usage: o2b brain graph-export [--vault <path>] [--out <file>]\n" +
"Serialise the vault knowledge graph (pages, wikilinks, typed relations) to a\n" +
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index 2084f052..7a4007c6 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -16,6 +16,7 @@ export { cmdBrainSetPrimary } from "./set-primary.ts";
export { cmdBrainProtect, cmdBrainUnprotect } from "./protect.ts";
export { cmdBrainRollback } from "./rollback.ts";
export { cmdBrainDoctor } from "./doctor.ts";
+export { cmdBrainWatchdog } from "./watchdog.ts";
export { cmdBrainHealth } from "./health.ts";
export { cmdBrainHistory } from "./history.ts";
export { cmdBrainAudit } from "./audit.ts";
@@ -32,12 +33,10 @@ export { cmdBrainMerge } from "./merge.ts";
export { cmdBrainExplorer } from "./explorer.ts";
export { cmdBrainExport } from "./export.ts";
export { cmdBrainUpgrade } from "./upgrade.ts";
-export {
- cmdBrainSnapshotDiff,
- handleBrainSnapshotSubcommand,
-} from "./snapshot.ts";
+export { cmdBrainSnapshotDiff, handleBrainSnapshotSubcommand } from "./snapshot.ts";
export { cmdBrainScanInline } from "./scan-inline.ts";
export { cmdBrainImportSession } from "./import-session.ts";
+export { cmdBrainSessionHook } from "./session-hook.ts";
export { cmdBrainImportClaudeMemory } from "./import-claude-memory.ts";
export { cmdBrainPageDedup } from "./page-dedup.ts";
export { cmdBrainTokenFootprint } from "./token-footprint.ts";
diff --git a/src/cli/brain/verbs/schema.ts b/src/cli/brain/verbs/schema.ts
index 0f714cf4..e23eba10 100644
--- a/src/cli/brain/verbs/schema.ts
+++ b/src/cli/brain/verbs/schema.ts
@@ -1,4 +1,14 @@
import { defaultConfigPath } from "../../../core/config.ts";
+import {
+ applySchemaAdminMutations,
+ buildSchemaGraph,
+ buildSchemaLint,
+ buildSchemaStats,
+ buildSchemaSyncResult,
+ explainSchemaToken,
+ parseSchemaMutationPayloads,
+ reviewSchemaOrphans,
+} from "../../../core/brain/schema-admin.ts";
import {
buildSchemaReport,
type BrainSchemaReport,
@@ -8,52 +18,132 @@ import { SCHEMA_VOCAB_CATEGORIES } from "../../../core/brain/schema-vocab.ts";
import { fail, parse, resolveBrainVault } from "../helpers.ts";
export async function cmdBrainSchema(argv: string[]): Promise<number> {
- const { flags } = parse(argv, {
+ const subcommands = new Set([
+ "report",
+ "stats",
+ "lint",
+ "graph",
+ "explain",
+ "orphans",
+ "apply",
+ "sync",
+ ]);
+ const firstArg = argv[0];
+ let subcommand = "report";
+ let args = argv;
+ if (firstArg !== undefined && !firstArg.startsWith("-")) {
+ if (!subcommands.has(firstArg)) return fail(`schema failed: unknown subcommand ${firstArg}`);
+ subcommand = firstArg;
+ args = argv.slice(1);
+ }
+ const { flags, positional } = parse(args, {
vault: { type: "string" },
json: { type: "boolean" },
+ mutation: { type: "string-array" },
+ actor: { type: "string", default: "cli" },
+ reason: { type: "string" },
+ "dry-run": { type: "boolean" },
+ "batch-size": { type: "string", default: "100" },
});
const config = defaultConfigPath();
- let report: BrainSchemaReport;
+ let vault: string;
try {
- const vault = resolveBrainVault(
- flags["vault"] as string | undefined,
- config,
- );
- report = buildSchemaReport(vault);
+ vault = resolveBrainVault(flags["vault"] as string | undefined, config);
} catch (exc) {
return fail(`schema failed: ${(exc as Error).message ?? exc}`);
}
- if (flags["json"]) {
- process.stdout.write(JSON.stringify(report, null, 2) + "\n");
- return 0;
+ try {
+ switch (subcommand) {
+ case "report": {
+ const report = buildSchemaReport(vault);
+ if (flags["json"]) return writeJson(report);
+ process.stdout.write(renderSchemaReportText(report));
+ return 0;
+ }
+ case "stats":
+ return writeResult(buildSchemaStats(vault), Boolean(flags["json"]), renderGenericText);
+ case "lint":
+ return writeResult(buildSchemaLint(vault), Boolean(flags["json"]), renderGenericText);
+ case "graph":
+ return writeResult(buildSchemaGraph(vault), Boolean(flags["json"]), renderGenericText);
+ case "explain": {
+ const token = positional[0];
+ if (!token) throw new Error("schema explain requires a token");
+ return writeResult(
+ explainSchemaToken(vault, token),
+ Boolean(flags["json"]),
+ renderGenericText,
+ );
+ }
+ case "orphans":
+ return writeResult(reviewSchemaOrphans(vault), Boolean(flags["json"]), renderGenericText);
+ case "apply": {
+ const mutationPayloads = (flags["mutation"] as string[] | undefined) ?? [];
+ if (mutationPayloads.length === 0) throw new Error("schema apply requires --mutation JSON");
+ const result = await applySchemaAdminMutations(
+ vault,
+ parseSchemaMutationPayloads(mutationPayloads),
+ {
+ actor: flags["actor"] as string,
+ reason: flags["reason"] as string | undefined,
+ },
+ );
+ return writeResult(result, Boolean(flags["json"]), renderGenericText);
+ }
+ case "sync": {
+ const batchSize = Number.parseInt(flags["batch-size"] as string, 10);
+ if (!Number.isInteger(batchSize) || batchSize <= 0) {
+ throw new Error("--batch-size must be a positive integer");
+ }
+ return writeResult(
+ buildSchemaSyncResult({
+ dryRun: Boolean(flags["dry-run"]),
+ batchSize,
+ }),
+ Boolean(flags["json"]),
+ renderGenericText,
+ );
+ }
+ }
+ } catch (exc) {
+ return fail(`schema failed: ${(exc as Error).message ?? exc}`);
}
- process.stdout.write(renderSchemaReportText(report));
+ return fail(`schema failed: unknown subcommand ${subcommand}`);
+}
+
+function writeResult<T>(value: T, json: boolean, renderText: (value: T) => string): number {
+ if (json) return writeJson(value);
+ process.stdout.write(renderText(value));
+ return 0;
+}
+
+function writeJson(value: unknown): number {
+ process.stdout.write(JSON.stringify(value, null, 2) + "\n");
return 0;
}
+function renderGenericText(value: unknown): string {
+ return JSON.stringify(value, null, 2) + "\n";
+}
+
function renderSchemaReportText(report: BrainSchemaReport): string {
const lines = ["brain schema", "", "vocabulary:"];
for (const category of SCHEMA_VOCAB_CATEGORIES) {
- lines.push(
- ` ${category}: ${report.vocabulary[category].join(", ") || "(none)"}`,
- );
+ lines.push(` ${category}: ${report.vocabulary[category].join(", ") || "(none)"}`);
}
lines.push("", "usage:");
for (const category of SCHEMA_VOCAB_CATEGORIES) {
- const usage = report.usage[category]
- .map((item) => `${item.token} x${item.count}`)
- .join(", ");
+ const usage = report.usage[category].map((item) => `${item.token} x${item.count}`).join(", ");
lines.push(` ${category} usage: ${usage || "(none)"}`);
}
lines.push("", "findings:");
if (report.findings.length === 0) {
lines.push(" none");
} else {
- for (const finding of report.findings)
- lines.push(` ${renderFinding(finding)}`);
+ for (const finding of report.findings) lines.push(` ${renderFinding(finding)}`);
}
return lines.join("\n") + "\n";
}
diff --git a/src/cli/brain/verbs/session-hook.ts b/src/cli/brain/verbs/session-hook.ts
new file mode 100644
index 00000000..5ead2761
--- /dev/null
+++ b/src/cli/brain/verbs/session-hook.ts
@@ -0,0 +1,37 @@
+import { defaultConfigPath, resolveAgentName } from "../../../core/config.ts";
+import { captureSessionLifecycleEvent } from "../../../core/brain/session-lifecycle.ts";
+import { readHookInput } from "../../../../hooks/lib/stdin.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainSessionHook(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ agent: { type: "string" },
+ "dry-run": { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const config = defaultConfigPath();
+ let payload: unknown;
+ try {
+ payload = await readHookInput();
+ } catch (err) {
+ return fail(`session-hook failed to read stdin: ${(err as Error).message ?? err}`);
+ }
+
+ try {
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ const agent = typeof flags["agent"] === "string" ? flags["agent"] : resolveAgentName(config);
+ const result = await captureSessionLifecycleEvent(vault, payload, {
+ agent,
+ dryRun: Boolean(flags["dry-run"]),
+ });
+ if (flags["json"]) okJson({ ...result });
+ else
+ ok(
+ `session-hook: ${result.event} created=${result.signals_created} deduped=${result.signals_deduped}`,
+ );
+ return 0;
+ } catch (err) {
+ return fail(`session-hook failed: ${(err as Error).message ?? err}`);
+ }
+}
diff --git a/src/cli/brain/verbs/watchdog.ts b/src/cli/brain/verbs/watchdog.ts
new file mode 100644
index 00000000..8c9d2862
--- /dev/null
+++ b/src/cli/brain/verbs/watchdog.ts
@@ -0,0 +1,51 @@
+import { defaultConfigPath } from "../../../core/config.ts";
+import { runBrainWatchdog } from "../../../core/brain/watchdog.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+export async function cmdBrainWatchdog(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ remediate: { type: "boolean" },
+ "dry-run": { type: "boolean" },
+ restore: { type: "string" },
+ "force-restore": { type: "boolean" },
+ attempt: { type: "string", default: "0" },
+ json: { type: "boolean" },
+ });
+ const config = defaultConfigPath();
+ try {
+ const rawAttempt = flags["attempt"] as string;
+ if (!/^\d+$/.test(rawAttempt)) return fail("--attempt must be a non-negative integer");
+ const attempt = Number(rawAttempt);
+ if (!Number.isSafeInteger(attempt)) return fail("--attempt must be a non-negative integer");
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ const result = runBrainWatchdog(vault, {
+ remediate: Boolean(flags["remediate"]),
+ dryRun: Boolean(flags["dry-run"]),
+ restoreRunId: flags["restore"] as string | undefined,
+ forceRestore: Boolean(flags["force-restore"]),
+ attempt,
+ });
+ if (flags["json"]) okJson({ ...result });
+ else ok(renderWatchdogText(result));
+ return result.restore.refused ? 2 : 0;
+ } catch (err) {
+ return fail(`watchdog failed: ${(err as Error).message ?? err}`);
+ }
+}
+
+function renderWatchdogText(result: ReturnType<typeof runBrainWatchdog>): string {
+ const lines = [
+ `watchdog: ${result.report.ok ? "ok" : "degraded"}`,
+ `checks: ok=${result.report.counts.ok} warning=${result.report.counts.warning} critical=${result.report.counts.critical}`,
+ ];
+ for (const check of result.report.checks)
+ lines.push(`${check.status}: ${check.name} - ${check.message}`);
+ if (result.remediation_plan.length > 0) {
+ lines.push("remediation:");
+ for (const item of result.remediation_plan) {
+ lines.push(`- ${item.action} ${item.target ?? item.command ?? ""}`.trim());
+ }
+ }
+ return lines.join("\n");
+}
diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.ts
index 66d1862f..3186f267 100644
--- a/src/cli/command-manifest.ts
+++ b/src/cli/command-manifest.ts
@@ -48,9 +48,7 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
flag("config", "string"),
flag("output", "string"),
]),
- command("index", "Regenerate the vault index from discovered pages", [
- flag("vault", "string"),
- ]),
+ command("index", "Regenerate the vault index from discovered pages", [flag("vault", "string")]),
command("mcp", "Run the optional MCP tool server", [
flag("vault", "string"),
flag("config", "string"),
@@ -63,9 +61,7 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
flag("max-tools", "string"),
]),
command("help", "Print command help or the command manifest"),
- command("completions", "Print shell completion script for o2b", [
- flag("shell", "string"),
- ]),
+ command("completions", "Print shell completion script for o2b", [flag("shell", "string")]),
command("install-cli", "Create symlinks for o2b and vault-log"),
command("install", "Multi-runtime install orchestrator"),
command("update", "Update Open Second Brain across detected runtimes", [
@@ -113,23 +109,47 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command("export", "Export active preferences"),
command("explorer", "Open or export Brain graph explorer"),
command("doctor", "Check Brain invariants"),
+ command("watchdog", "Probe Brain recovery status"),
command("health", "Render semantic Brain health"),
command("history", "Render preference edit history"),
command("audit", "Render mutation audit trail"),
command("morning-brief", "Render session-start summary"),
command("codec", "Compress or expand session prose"),
command("sources", "Show signal source dashboard"),
- command("schema", "Inspect Brain schema vocabulary"),
+ command(
+ "schema",
+ "Inspect Brain schema vocabulary",
+ [flag("vault", "string")],
+ [
+ command("report", "Inspect Brain schema vocabulary", [flag("vault", "string")]),
+ command("stats", "Summarise Brain schema vocabulary", [flag("vault", "string")]),
+ command("lint", "Lint Brain schema vocabulary", [flag("vault", "string")]),
+ command("graph", "Render Brain schema graph", [flag("vault", "string")]),
+ command("explain", "Explain a Brain schema token", [flag("vault", "string")]),
+ command("orphans", "Review unused Brain schema declarations", [
+ flag("vault", "string"),
+ ]),
+ command("apply", "Apply audited Brain schema mutations", [
+ flag("vault", "string"),
+ flag("mutation", "string-array"),
+ flag("actor", "string"),
+ flag("reason", "string"),
+ ]),
+ command("sync", "Preview Brain schema sync", [
+ flag("vault", "string"),
+ flag("dry-run", "boolean"),
+ flag("batch-size", "string"),
+ ]),
+ ],
+ ),
command("graph-export", "Export vault graph"),
command("graph-import", "Import vault graph stubs"),
command("backlinks", "List inbound Brain references"),
command("semantics-backfill", "Preview Brain semantics backfill"),
- command(
- "mcp-landscape",
- "List MCP servers configured across the vault",
- ),
+ command("mcp-landscape", "List MCP servers configured across the vault"),
command("scan-inline", "Capture inline @osb markers"),
command("import-session", "Replay registered agent sessions"),
+ command("session-hook", "Capture runtime lifecycle hook payloads"),
command("import-claude-memory", "Import Claude memory feedback"),
],
),
@@ -184,22 +204,16 @@ export function manifestForJson(): CliRootManifest {
return addInheritedFlags(CLI_COMMAND_MANIFEST);
}
-export function commandNames(
- manifest: CliRootManifest = CLI_COMMAND_MANIFEST,
-): string[] {
+export function commandNames(manifest: CliRootManifest = CLI_COMMAND_MANIFEST): string[] {
return manifest.commands.map((item) => item.name);
}
export function nestedCommandNames(parent: string): string[] {
- const node = CLI_COMMAND_MANIFEST.commands.find(
- (item) => item.name === parent,
- );
+ const node = CLI_COMMAND_MANIFEST.commands.find((item) => item.name === parent);
return node?.commands?.map((item) => item.name) ?? [];
}
-export function allFlagNames(
- manifest: CliRootManifest = manifestForJson(),
-): string[] {
+export function allFlagNames(manifest: CliRootManifest = manifestForJson()): string[] {
const names = new Set<string>();
for (const flagSpec of manifest.flags) names.add(flagSpec.name);
const visit = (items: ReadonlyArray<CliCommandManifest>): void => {
@@ -237,21 +251,15 @@ function addInheritedFlags(root: CliRootManifest): CliRootManifest {
};
}
-function addInheritedFlagsToCommand(
- commandSpec: CliCommandManifest,
-): CliCommandManifest {
+function addInheritedFlagsToCommand(commandSpec: CliCommandManifest): CliCommandManifest {
const ownFlags = commandSpec.flags ?? [];
- const hasJson = ownFlags.some(
- (item) => item.name === INHERITED_JSON_FLAG.name,
- );
+ const hasJson = ownFlags.some((item) => item.name === INHERITED_JSON_FLAG.name);
return {
...commandSpec,
flags: hasJson ? ownFlags : [...ownFlags, INHERITED_JSON_FLAG],
...(commandSpec.commands
? {
- commands: commandSpec.commands.map((item) =>
- addInheritedFlagsToCommand(item),
- ),
+ commands: commandSpec.commands.map((item) => addInheritedFlagsToCommand(item)),
}
: {}),
};
diff --git a/src/core/brain/policy.ts b/src/core/brain/policy.ts
index ba75f8ab..c92ccb04 100644
--- a/src/core/brain/policy.ts
+++ b/src/core/brain/policy.ts
@@ -48,10 +48,7 @@ import {
// break the module-init cycle: the resolver lives in `index.ts` and
// itself imports `loadBrainConfig` from this file. See the
// `defaults.ts` header for the rationale.
-import {
- classifyVaultIgnoreRule,
- DEFAULT_VAULT_IGNORE_PATHS,
-} from "../vault-scope/defaults.ts";
+import { classifyVaultIgnoreRule, DEFAULT_VAULT_IGNORE_PATHS } from "../vault-scope/defaults.ts";
import { brainConfigPath } from "./paths.ts";
/** Schema versions this build understands. Bump on incompatible changes. */
@@ -99,36 +96,30 @@ export const INSTRUCTION_FILE_MAX_LINES_CEILING = 10000;
* - `instruction_file_max_lines: 200` matches the documented
* compliance ceiling.
*/
-export const BRAIN_GUARDRAIL_DEFAULTS: ResolvedBrainGuardrailConfig =
- Object.freeze({
- promotion_min_signals: 1,
- promotion_min_distinct_agents: 1,
- promotion_min_age_days: 0,
- instruction_file_max_lines: 200,
- }) as ResolvedBrainGuardrailConfig;
+export const BRAIN_GUARDRAIL_DEFAULTS: ResolvedBrainGuardrailConfig = Object.freeze({
+ promotion_min_signals: 1,
+ promotion_min_distinct_agents: 1,
+ promotion_min_age_days: 0,
+ instruction_file_max_lines: 200,
+}) as ResolvedBrainGuardrailConfig;
/**
* Merge a parsed `guardrails` block (or `undefined`) with
* `BRAIN_GUARDRAIL_DEFAULTS`. Returns a fully-populated struct so
* consumers do not branch on optional fields.
*/
-export function resolveGuardrails(
- cfg: BrainConfig,
-): ResolvedBrainGuardrailConfig {
+export function resolveGuardrails(cfg: BrainConfig): ResolvedBrainGuardrailConfig {
const g = cfg.guardrails;
if (g === undefined) return BRAIN_GUARDRAIL_DEFAULTS;
return {
promotion_min_signals:
g.promotion_min_signals ?? BRAIN_GUARDRAIL_DEFAULTS.promotion_min_signals,
promotion_min_distinct_agents:
- g.promotion_min_distinct_agents ??
- BRAIN_GUARDRAIL_DEFAULTS.promotion_min_distinct_agents,
+ g.promotion_min_distinct_agents ?? BRAIN_GUARDRAIL_DEFAULTS.promotion_min_distinct_agents,
promotion_min_age_days:
- g.promotion_min_age_days ??
- BRAIN_GUARDRAIL_DEFAULTS.promotion_min_age_days,
+ g.promotion_min_age_days ?? BRAIN_GUARDRAIL_DEFAULTS.promotion_min_age_days,
instruction_file_max_lines:
- g.instruction_file_max_lines ??
- BRAIN_GUARDRAIL_DEFAULTS.instruction_file_max_lines,
+ g.instruction_file_max_lines ?? BRAIN_GUARDRAIL_DEFAULTS.instruction_file_max_lines,
};
}
@@ -149,31 +140,25 @@ export function resolveGuardrails(
* vault-root instruction file `brain_context` surfaces when
* present. Configurable per vault.
*/
-export const BRAIN_LINK_GRAPH_DEFAULTS: ResolvedBrainLinkGraphConfig =
- Object.freeze({
- moc_min_outbound_links: 5,
- moc_min_link_ratio: 0.3,
- vault_instruction_file: "VAULT.md",
- }) as ResolvedBrainLinkGraphConfig;
+export const BRAIN_LINK_GRAPH_DEFAULTS: ResolvedBrainLinkGraphConfig = Object.freeze({
+ moc_min_outbound_links: 5,
+ moc_min_link_ratio: 0.3,
+ vault_instruction_file: "VAULT.md",
+}) as ResolvedBrainLinkGraphConfig;
/**
* Merge a parsed `link_graph` block (or `undefined`) with
* `BRAIN_LINK_GRAPH_DEFAULTS`.
*/
-export function resolveLinkGraph(
- cfg: BrainConfig,
-): ResolvedBrainLinkGraphConfig {
+export function resolveLinkGraph(cfg: BrainConfig): ResolvedBrainLinkGraphConfig {
const lg = cfg.link_graph;
if (lg === undefined) return BRAIN_LINK_GRAPH_DEFAULTS;
return {
moc_min_outbound_links:
- lg.moc_min_outbound_links ??
- BRAIN_LINK_GRAPH_DEFAULTS.moc_min_outbound_links,
- moc_min_link_ratio:
- lg.moc_min_link_ratio ?? BRAIN_LINK_GRAPH_DEFAULTS.moc_min_link_ratio,
+ lg.moc_min_outbound_links ?? BRAIN_LINK_GRAPH_DEFAULTS.moc_min_outbound_links,
+ moc_min_link_ratio: lg.moc_min_link_ratio ?? BRAIN_LINK_GRAPH_DEFAULTS.moc_min_link_ratio,
vault_instruction_file:
- lg.vault_instruction_file ??
- BRAIN_LINK_GRAPH_DEFAULTS.vault_instruction_file,
+ lg.vault_instruction_file ?? BRAIN_LINK_GRAPH_DEFAULTS.vault_instruction_file,
};
}
@@ -192,14 +177,13 @@ export function resolveLinkGraph(
* - `daily_window_offset_hours: 0` - daily-brief windows align
* with UTC midnight by default.
*/
-export const BRAIN_TEMPORAL_DEFAULTS: ResolvedBrainTemporalConfig =
- Object.freeze({
- stale_pref_days: 90,
- stale_signal_days: 30,
- stale_log_days: 180,
- weekly_start_dow: 1,
- daily_window_offset_hours: 0,
- }) as ResolvedBrainTemporalConfig;
+export const BRAIN_TEMPORAL_DEFAULTS: ResolvedBrainTemporalConfig = Object.freeze({
+ stale_pref_days: 90,
+ stale_signal_days: 30,
+ stale_log_days: 180,
+ weekly_start_dow: 1,
+ daily_window_offset_hours: 0,
+}) as ResolvedBrainTemporalConfig;
/**
* Merge a parsed `temporal` block (or `undefined`) with
@@ -209,16 +193,12 @@ export function resolveTemporal(cfg: BrainConfig): ResolvedBrainTemporalConfig {
const tp = cfg.temporal;
if (tp === undefined) return BRAIN_TEMPORAL_DEFAULTS;
return {
- stale_pref_days:
- tp.stale_pref_days ?? BRAIN_TEMPORAL_DEFAULTS.stale_pref_days,
- stale_signal_days:
- tp.stale_signal_days ?? BRAIN_TEMPORAL_DEFAULTS.stale_signal_days,
+ stale_pref_days: tp.stale_pref_days ?? BRAIN_TEMPORAL_DEFAULTS.stale_pref_days,
+ stale_signal_days: tp.stale_signal_days ?? BRAIN_TEMPORAL_DEFAULTS.stale_signal_days,
stale_log_days: tp.stale_log_days ?? BRAIN_TEMPORAL_DEFAULTS.stale_log_days,
- weekly_start_dow:
- tp.weekly_start_dow ?? BRAIN_TEMPORAL_DEFAULTS.weekly_start_dow,
+ weekly_start_dow: tp.weekly_start_dow ?? BRAIN_TEMPORAL_DEFAULTS.weekly_start_dow,
daily_window_offset_hours:
- tp.daily_window_offset_hours ??
- BRAIN_TEMPORAL_DEFAULTS.daily_window_offset_hours,
+ tp.daily_window_offset_hours ?? BRAIN_TEMPORAL_DEFAULTS.daily_window_offset_hours,
};
}
@@ -252,16 +232,12 @@ export function resolveHealth(cfg: BrainConfig): ResolvedBrainHealthConfig {
const h = cfg.health;
if (h === undefined) return BRAIN_HEALTH_DEFAULTS;
return {
- contradiction_jaccard:
- h.contradiction_jaccard ?? BRAIN_HEALTH_DEFAULTS.contradiction_jaccard,
+ contradiction_jaccard: h.contradiction_jaccard ?? BRAIN_HEALTH_DEFAULTS.contradiction_jaccard,
concept_gap_min_frequency:
- h.concept_gap_min_frequency ??
- BRAIN_HEALTH_DEFAULTS.concept_gap_min_frequency,
+ h.concept_gap_min_frequency ?? BRAIN_HEALTH_DEFAULTS.concept_gap_min_frequency,
stale_claim_max_age_days:
- h.stale_claim_max_age_days ??
- BRAIN_HEALTH_DEFAULTS.stale_claim_max_age_days,
- remediation_step_cap:
- h.remediation_step_cap ?? BRAIN_HEALTH_DEFAULTS.remediation_step_cap,
+ h.stale_claim_max_age_days ?? BRAIN_HEALTH_DEFAULTS.stale_claim_max_age_days,
+ remediation_step_cap: h.remediation_step_cap ?? BRAIN_HEALTH_DEFAULTS.remediation_step_cap,
};
}
@@ -312,9 +288,7 @@ export function loadNotesConfigSafe(vault: string): ResolvedBrainNotesConfig {
* consumer (MCP wrappers, CLI verbs) so a freshly-initialised vault
* still produces a useful report.
*/
-export function loadTemporalConfigSafe(
- vault: string,
-): ResolvedBrainTemporalConfig {
+export function loadTemporalConfigSafe(vault: string): ResolvedBrainTemporalConfig {
try {
return resolveTemporal(loadBrainConfig(vault));
} catch {
@@ -538,10 +512,7 @@ export function loadBrainConfigDetailed(vault: string): LoadBrainConfigResult {
* a synthetic label like `"<test fixture>"` so the failure points at
* something useful.
*/
-export function validateBrainConfig(
- parsed: unknown,
- source: string | null = null,
-): BrainConfig {
+export function validateBrainConfig(parsed: unknown, source: string | null = null): BrainConfig {
return validateBrainConfigDetailed(parsed, source).config;
}
@@ -555,11 +526,7 @@ export function validateBrainConfigDetailed(
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,
- );
+ throw new BrainConfigError("config root must be a map of keys", null, source);
}
const obj = parsed as Record<string, unknown>;
const warnings: BrainConfigLoadWarning[] = [];
@@ -636,16 +603,8 @@ export function validateBrainConfigDetailed(
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.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,
@@ -658,25 +617,15 @@ export function validateBrainConfigDetailed(
DEFAULT_BRAIN_CONFIG.retire as unknown as Readonly<Record<string, number>>,
source,
);
- requirePositiveInteger(
- "retire.stale_evidence_days",
- retire.stale_evidence_days,
- 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,
+ DEFAULT_BRAIN_CONFIG.confidence as unknown as Readonly<Record<string, number>>,
source,
);
+ requireNonNegativeInteger("confidence.low_max_applied", confidence.low_max_applied, source);
requireUnitInterval("confidence.medium_min", confidence.medium_min, source);
requireUnitInterval("confidence.high_min", confidence.high_min, source);
if ((confidence.medium_min as number) >= (confidence.high_min as number)) {
@@ -691,16 +640,10 @@ export function validateBrainConfigDetailed(
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,
+ DEFAULT_BRAIN_CONFIG.snapshots as unknown as Readonly<Record<string, number>>,
source,
);
+ requirePositiveInteger("snapshots.retention_count", snapshots.retention_count, source);
// Optional `vault` block (v0.10.9). Hard-error on shape problems β€”
// exclusions affect every walker, silent ignore would be a footgun.
@@ -803,11 +746,7 @@ export function validateBrainConfigDetailed(
let active: BrainActiveConfig | undefined;
if ("active" in obj) {
const rawActive = obj["active"];
- if (
- typeof rawActive !== "object" ||
- rawActive === null ||
- Array.isArray(rawActive)
- ) {
+ if (typeof rawActive !== "object" || rawActive === null || Array.isArray(rawActive)) {
throw new BrainConfigError(
`block must be a map of keys; got ${describe(rawActive)}`,
"active",
@@ -822,9 +761,7 @@ export function validateBrainConfigDetailed(
const windowDays = hasWindow
? activeMap["most_applied_window_days"]
: MOST_APPLIED_WINDOW_DAYS_DEFAULT;
- const limit = hasLimit
- ? activeMap["most_applied_limit"]
- : MOST_APPLIED_LIMIT_DEFAULT;
+ const limit = hasLimit ? activeMap["most_applied_limit"] : MOST_APPLIED_LIMIT_DEFAULT;
if (
typeof windowDays !== "number" ||
!Number.isInteger(windowDays) ||
@@ -926,9 +863,7 @@ export function validateBrainConfigDetailed(
});
ok = false;
} else {
- const badIdx = (drObj["known_agents"] as unknown[]).findIndex(
- (v) => typeof v !== "string",
- );
+ const badIdx = (drObj["known_agents"] as unknown[]).findIndex((v) => typeof v !== "string");
if (badIdx >= 0) {
warnings.push({
path: source ?? "<config>",
@@ -986,9 +921,7 @@ export function validateBrainConfigDetailed(
rawMap["promotion_min_distinct_agents"],
source,
);
- partial.promotion_min_distinct_agents = rawMap[
- "promotion_min_distinct_agents"
- ] as number;
+ partial.promotion_min_distinct_agents = rawMap["promotion_min_distinct_agents"] as number;
}
if ("promotion_min_age_days" in rawMap) {
requireNonNegativeInteger(
@@ -996,9 +929,7 @@ export function validateBrainConfigDetailed(
rawMap["promotion_min_age_days"],
source,
);
- partial.promotion_min_age_days = rawMap[
- "promotion_min_age_days"
- ] as number;
+ partial.promotion_min_age_days = rawMap["promotion_min_age_days"] as number;
}
if ("instruction_file_max_lines" in rawMap) {
requirePositiveInteger(
@@ -1054,11 +985,7 @@ export function validateBrainConfigDetailed(
if ("link_graph" in obj) {
const rawLg = obj["link_graph"];
if (typeof rawLg !== "object" || rawLg === null || Array.isArray(rawLg)) {
- throw new BrainConfigError(
- "link_graph must be a mapping",
- "link_graph",
- source,
- );
+ throw new BrainConfigError("link_graph must be a mapping", "link_graph", source);
}
const lgObj = rawLg as Record<string, unknown>;
const partialLg: Record<string, unknown> = {};
@@ -1100,11 +1027,7 @@ export function validateBrainConfigDetailed(
// Reject absolute paths and `..` traversal at load time so
// the config surface fails loudly instead of silently
// omitting the envelope field at read time.
- if (
- trimmed.startsWith("/") ||
- trimmed.startsWith("\\") ||
- trimmed.includes("..")
- ) {
+ if (trimmed.startsWith("/") || trimmed.startsWith("\\") || trimmed.includes("..")) {
throw new BrainConfigError(
"must be a vault-relative path without '..' segments",
"link_graph.vault_instruction_file",
@@ -1126,10 +1049,7 @@ export function validateBrainConfigDetailed(
});
}
}
- linkGraph =
- Object.keys(partialLg).length > 0
- ? (partialLg as BrainLinkGraphConfig)
- : {};
+ linkGraph = Object.keys(partialLg).length > 0 ? (partialLg as BrainLinkGraphConfig) : {};
}
// Optional `temporal` block (v0.10.18). Shape:
@@ -1145,11 +1065,7 @@ export function validateBrainConfigDetailed(
if ("temporal" in obj) {
const rawTp = obj["temporal"];
if (typeof rawTp !== "object" || rawTp === null || Array.isArray(rawTp)) {
- throw new BrainConfigError(
- "temporal must be a mapping",
- "temporal",
- source,
- );
+ throw new BrainConfigError("temporal must be a mapping", "temporal", source);
}
const tpObj = rawTp as Record<string, unknown>;
const partialTp: Record<string, unknown> = {};
@@ -1160,11 +1076,7 @@ export function validateBrainConfigDetailed(
if (key in tpObj) {
const v = tpObj[key];
if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
- throw new BrainConfigError(
- "must be a positive integer",
- `temporal.${key}`,
- source,
- );
+ throw new BrainConfigError("must be a positive integer", `temporal.${key}`, source);
}
partialTp[key] = v;
}
@@ -1207,10 +1119,7 @@ export function validateBrainConfigDetailed(
});
}
}
- temporal =
- Object.keys(partialTp).length > 0
- ? (partialTp as BrainTemporalConfig)
- : {};
+ temporal = Object.keys(partialTp).length > 0 ? (partialTp as BrainTemporalConfig) : {};
}
// Optional `health:` block (v0.14.0). Shape:
@@ -1241,23 +1150,13 @@ export function validateBrainConfigDetailed(
partialH["contradiction_jaccard"] = v;
}
const positiveIntKeys: ReadonlyArray<
- | "concept_gap_min_frequency"
- | "stale_claim_max_age_days"
- | "remediation_step_cap"
- > = [
- "concept_gap_min_frequency",
- "stale_claim_max_age_days",
- "remediation_step_cap",
- ];
+ "concept_gap_min_frequency" | "stale_claim_max_age_days" | "remediation_step_cap"
+ > = ["concept_gap_min_frequency", "stale_claim_max_age_days", "remediation_step_cap"];
for (const key of positiveIntKeys) {
if (key in hObj) {
const v = hObj[key];
if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
- throw new BrainConfigError(
- "must be a positive integer",
- `health.${key}`,
- source,
- );
+ throw new BrainConfigError("must be a positive integer", `health.${key}`, source);
}
partialH[key] = v;
}
@@ -1276,8 +1175,7 @@ export function validateBrainConfigDetailed(
});
}
}
- health =
- Object.keys(partialH).length > 0 ? (partialH as BrainHealthConfig) : {};
+ health = Object.keys(partialH).length > 0 ? (partialH as BrainHealthConfig) : {};
}
// Optional `notes:` block (v0.11.0). Shape:
@@ -1291,11 +1189,7 @@ export function validateBrainConfigDetailed(
let notes: BrainNotesConfig | undefined;
if ("notes" in obj) {
const rawNotes = obj["notes"];
- if (
- typeof rawNotes !== "object" ||
- rawNotes === null ||
- Array.isArray(rawNotes)
- ) {
+ if (typeof rawNotes !== "object" || rawNotes === null || Array.isArray(rawNotes)) {
throw new BrainConfigError("notes must be a mapping", "notes", source);
}
const notesObj = rawNotes as Record<string, unknown>;
@@ -1354,10 +1248,7 @@ export function validateBrainConfigDetailed(
});
}
}
- notes =
- Object.keys(partialNotes).length > 0
- ? (partialNotes as BrainNotesConfig)
- : {};
+ notes = Object.keys(partialNotes).length > 0 ? (partialNotes as BrainNotesConfig) : {};
}
// Optional `schema:` block (runtime schema-pack foundation). Shape:
@@ -1366,22 +1257,21 @@ export function validateBrainConfigDetailed(
// signal_types: [observation]
// page_types: [paper]
// log_event_kinds: [milestone]
+ // aliases: [decision=choice]
+ // prefixes: [pref=decision]
+ // link_types: [supports]
+ // extractable: [decision]
+ // expert_routing: [decision=schema-author]
// Absent block leaves cfg.schema undefined; consumers merge built-ins
// through resolveSchemaVocabulary.
let schema: BrainSchemaConfig | undefined;
if ("schema" in obj) {
const rawSchema = obj["schema"];
- if (
- typeof rawSchema !== "object" ||
- rawSchema === null ||
- Array.isArray(rawSchema)
- ) {
+ if (typeof rawSchema !== "object" || rawSchema === null || Array.isArray(rawSchema)) {
throw new BrainConfigError("schema must be a mapping", "schema", source);
}
const schemaObj = rawSchema as Record<string, unknown>;
- const partialSchema: Partial<
- Record<keyof BrainSchemaConfig, ReadonlyArray<string>>
- > = {};
+ const partialSchema: Partial<Record<keyof BrainSchemaConfig, ReadonlyArray<string>>> = {};
for (const category of SCHEMA_VOCAB_CATEGORIES) {
if (!(category in schemaObj)) continue;
const value = schemaObj[category];
@@ -1394,8 +1284,47 @@ export function validateBrainConfigDetailed(
}
partialSchema[category] = value;
}
+ const schemaMetaKeys = [
+ "aliases",
+ "prefixes",
+ "link_types",
+ "extractable",
+ "expert_routing",
+ ] as const;
+ for (const key of schemaMetaKeys) {
+ if (!(key in schemaObj)) continue;
+ const value = schemaObj[key];
+ if (!Array.isArray(value)) {
+ throw new BrainConfigError(
+ "must be an array of schema metadata entries",
+ `schema.${key}`,
+ source,
+ );
+ }
+ partialSchema[key] = value.map((entry, index) => {
+ if (typeof entry !== "string") {
+ throw new BrainConfigError(
+ "must be a string schema metadata entry",
+ `schema.${key}[${index}]`,
+ source,
+ );
+ }
+ const trimmed = entry.trim();
+ if (trimmed.length === 0) {
+ throw new BrainConfigError(
+ "must be a non-empty schema metadata entry",
+ `schema.${key}[${index}]`,
+ source,
+ );
+ }
+ return trimmed;
+ });
+ }
for (const key of Object.keys(schemaObj)) {
- if (!(SCHEMA_VOCAB_CATEGORIES as ReadonlyArray<string>).includes(key)) {
+ if (
+ !(SCHEMA_VOCAB_CATEGORIES as ReadonlyArray<string>).includes(key) &&
+ !(schemaMetaKeys as ReadonlyArray<string>).includes(key)
+ ) {
warnings.push({
path: source ?? "<config>",
message: `schema.${key}: unknown field ignored (forward-compat)`,
@@ -1403,7 +1332,15 @@ export function validateBrainConfigDetailed(
}
}
try {
- schema = validateSchemaDeclarations(partialSchema) as BrainSchemaConfig;
+ const declarations = validateSchemaDeclarations(partialSchema);
+ schema = {
+ ...declarations,
+ ...(partialSchema.aliases ? { aliases: partialSchema.aliases } : {}),
+ ...(partialSchema.prefixes ? { prefixes: partialSchema.prefixes } : {}),
+ ...(partialSchema.link_types ? { link_types: partialSchema.link_types } : {}),
+ ...(partialSchema.extractable ? { extractable: partialSchema.extractable } : {}),
+ ...(partialSchema.expert_routing ? { expert_routing: partialSchema.expert_routing } : {}),
+ } as BrainSchemaConfig;
} catch (err) {
if (err instanceof SchemaVocabularyError) {
const detail = err.message.startsWith(`${err.field}: `)
@@ -1466,9 +1403,7 @@ export function validateBrainConfigDetailed(
},
...(vault !== undefined ? { vault } : {}),
...(active !== undefined ? { active } : {}),
- ...(disciplineReport !== undefined
- ? { discipline_report: disciplineReport }
- : {}),
+ ...(disciplineReport !== undefined ? { discipline_report: disciplineReport } : {}),
...(guardrails !== undefined ? { guardrails } : {}),
...(linkGraph !== undefined ? { link_graph: linkGraph } : {}),
...(temporal !== undefined ? { temporal } : {}),
@@ -1511,25 +1446,13 @@ function mergeBlock(
return merged;
}
-function requirePositiveInteger(
- field: string,
- value: unknown,
- source: string | null,
-): void {
+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,
- );
+ throw new BrainConfigError(`must be a positive integer; got ${describe(value)}`, field, source);
}
}
-function requireNonNegativeInteger(
- field: string,
- value: unknown,
- source: string | null,
-): void {
+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)}`,
@@ -1539,22 +1462,9 @@ function requireNonNegativeInteger(
}
}
-function requireUnitInterval(
- field: string,
- value: unknown,
- source: string | null,
-): void {
- if (
- typeof value !== "number" ||
- !Number.isFinite(value) ||
- value < 0 ||
- value > 1
- ) {
- throw new BrainConfigError(
- `must be a number in [0, 1]; got ${describe(value)}`,
- field,
- source,
- );
+function requireUnitInterval(field: string, value: unknown, source: string | null): void {
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+ throw new BrainConfigError(`must be a number in [0, 1]; got ${describe(value)}`, field, source);
}
}
@@ -1606,9 +1516,7 @@ export function parseBrainYaml(text: string): ParsedBlock {
while (i < lines.length) {
const line = lines[i]!;
if (line.indent !== 0) {
- throw new Error(
- `line ${line.lineNumber}: unexpected indentation at top level`,
- );
+ throw new Error(`line ${line.lineNumber}: unexpected indentation at top level`);
}
const kv = splitKeyValue(line);
if (kv.value === "") {
@@ -1619,11 +1527,7 @@ export function parseBrainYaml(text: string): ParsedBlock {
const child: Record<string, ParsedScalar | ParsedScalar[]> = {};
i++;
const blockIndent = detectBlockIndent(lines, i);
- while (
- i < lines.length &&
- lines[i]!.indent >= blockIndent &&
- blockIndent > 0
- ) {
+ while (i < lines.length && lines[i]!.indent >= blockIndent && blockIndent > 0) {
const inner = lines[i]!;
if (inner.indent !== blockIndent) {
throw new Error(
@@ -1656,10 +1560,7 @@ export function parseBrainYaml(text: string): ParsedBlock {
`(expected ${listIndent} spaces, got ${listLine.indent})`,
);
}
- if (
- !listLine.content.startsWith("- ") &&
- listLine.content !== "-"
- ) {
+ if (!listLine.content.startsWith("- ") && listLine.content !== "-") {
// If it looks like a `key: value` pair, it's a deeper block β€” not
// supported. Preserve the original error message so existing tests
// that assert on the wording keep passing.
@@ -1732,8 +1633,7 @@ function splitLines(text: string): Line[] {
let content = stripped;
if (!/['"]/.test(stripped)) {
const hashIdx = stripped.indexOf(" #");
- if (hashIdx >= 0)
- content = stripped.slice(0, hashIdx).replace(/\s+$/, "");
+ if (hashIdx >= 0) content = stripped.slice(0, hashIdx).replace(/\s+$/, "");
}
const indent = content.length - content.trimStart().length;
out.push({
@@ -1760,9 +1660,7 @@ function splitKeyValue(line: Line): KeyValue {
}
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)}`,
- );
+ throw new Error(`line ${line.lineNumber}: invalid key name: ${JSON.stringify(key)}`);
}
const value = line.content.slice(idx + 1).trim();
return { key, value };
@@ -1775,17 +1673,13 @@ function detectBlockIndent(lines: Line[], cursor: number): number {
return first.indent;
}
-function parseScalar(
- text: string,
- lineNumber: number,
-): ParsedScalar | ParsedScalar[] {
+function parseScalar(text: string, lineNumber: number): ParsedScalar | ParsedScalar[] {
if (text.startsWith("[") && text.endsWith("]")) {
return parseInlineArray(text.slice(1, -1), lineNumber);
}
if (
text.length >= 2 &&
- ((text.startsWith('"') && text.endsWith('"')) ||
- (text.startsWith("'") && text.endsWith("'")))
+ ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))
) {
return text.slice(1, -1);
}
@@ -1807,10 +1701,7 @@ function parseScalar(
return text;
}
-function parseInlineArray(
- innerRaw: string,
- lineNumber: number,
-): ParsedScalar[] {
+function parseInlineArray(innerRaw: string, lineNumber: number): ParsedScalar[] {
const inner = innerRaw.trim();
if (inner === "") return [];
@@ -1843,9 +1734,7 @@ function parseInlineArray(
current += ch;
}
if (inQuote) {
- throw new Error(
- `line ${lineNumber}: unterminated quoted string in inline array`,
- );
+ throw new Error(`line ${lineNumber}: unterminated quoted string in inline array`);
}
out.push(parseInlineArrayItem(current, lineNumber));
return out;
@@ -1858,9 +1747,7 @@ function parseInlineArrayItem(text: string, lineNumber: number): ParsedScalar {
}
const parsed = parseScalar(trimmed, lineNumber);
if (Array.isArray(parsed)) {
- throw new Error(
- `line ${lineNumber}: nested inline arrays are not supported`,
- );
+ throw new Error(`line ${lineNumber}: nested inline arrays are not supported`);
}
return parsed;
}
diff --git a/src/core/brain/schema-admin.ts b/src/core/brain/schema-admin.ts
new file mode 100644
index 00000000..3431306d
--- /dev/null
+++ b/src/core/brain/schema-admin.ts
@@ -0,0 +1,346 @@
+import { brainConfigPath } from "./paths.ts";
+import {
+ buildSchemaReport,
+ type BrainSchemaReport,
+ type SchemaReportFinding,
+} from "./schema-report.ts";
+import { loadSchemaPack, type SchemaPack } from "./schema-pack.ts";
+import {
+ applySchemaMutations,
+ type ApplySchemaMutationsResult,
+ type SchemaMutation,
+} from "./schema-mutate.ts";
+import {
+ DEFAULT_SCHEMA_VOCAB,
+ SCHEMA_VOCAB_CATEGORIES,
+ normalizeSchemaToken,
+ type SchemaVocabularyCategory,
+} from "./schema-vocab.ts";
+
+export interface SchemaStats {
+ readonly declared: Record<SchemaVocabularyCategory, number>;
+ readonly vocabulary: Record<SchemaVocabularyCategory, number>;
+ readonly used: Record<SchemaVocabularyCategory, number>;
+ readonly metadata: {
+ readonly aliases: number;
+ readonly prefixes: number;
+ readonly link_types: number;
+ readonly extractable: number;
+ readonly expert_routing: number;
+ };
+ readonly findings: number;
+}
+
+export interface SchemaGraphNode {
+ readonly id: string;
+ readonly kind: "type" | "link_type" | "expert";
+ readonly category?: SchemaVocabularyCategory;
+ readonly builtin?: boolean;
+}
+
+export interface SchemaGraphEdge {
+ readonly from: string;
+ readonly to: string;
+ readonly kind: "alias" | "prefix" | "extractable" | "expert_routing";
+ readonly label?: string;
+}
+
+export interface SchemaGraph {
+ readonly nodes: ReadonlyArray<SchemaGraphNode>;
+ readonly edges: ReadonlyArray<SchemaGraphEdge>;
+}
+
+export interface SchemaExplanation {
+ readonly token: string;
+ readonly categories: ReadonlyArray<SchemaVocabularyCategory>;
+ readonly declared: ReadonlyArray<SchemaVocabularyCategory>;
+ readonly builtin: ReadonlyArray<SchemaVocabularyCategory>;
+ readonly usage: Record<SchemaVocabularyCategory, number>;
+ readonly aliases: ReadonlyArray<string>;
+ readonly prefixes: ReadonlyArray<string>;
+ readonly link_type: boolean;
+ readonly extractable: boolean;
+ readonly expert: string | null;
+}
+
+export interface SchemaOrphanReport {
+ readonly orphans: ReadonlyArray<SchemaReportFinding>;
+}
+
+export interface SchemaSyncResult {
+ readonly dry_run: boolean;
+ readonly batch_size: number;
+ readonly updated: number;
+ readonly skipped: number;
+ readonly note: string;
+}
+
+export function getActiveSchemaPack(vault: string): {
+ path: string;
+ pack: SchemaPack;
+} {
+ return { path: brainConfigPath(vault), pack: loadSchemaPack(vault) };
+}
+
+export function listSchemaPacks(vault: string): {
+ active: string;
+ packs: ReadonlyArray<{ name: string; path: string; active: boolean }>;
+} {
+ const active = brainConfigPath(vault);
+ return { active, packs: [{ name: "active", path: active, active: true }] };
+}
+
+export function buildSchemaStats(vault: string): SchemaStats {
+ const pack = loadSchemaPack(vault);
+ const report = buildSchemaReport(vault);
+ const declared = emptyCounts();
+ const vocabulary = emptyCounts();
+ const used = emptyCounts();
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ declared[category] = (pack.declarations[category] ?? []).length;
+ vocabulary[category] = pack.vocabulary[category].length;
+ used[category] = sumUsage(report, category);
+ }
+ return {
+ declared,
+ vocabulary,
+ used,
+ metadata: {
+ aliases: Object.values(pack.aliases).reduce((sum, values) => sum + values.length, 0),
+ prefixes: Object.keys(pack.prefixes).length,
+ link_types: pack.link_types.length,
+ extractable: pack.extractable.length,
+ expert_routing: Object.keys(pack.expert_routing).length,
+ },
+ findings: report.findings.length,
+ };
+}
+
+export function buildSchemaLint(vault: string): {
+ findings: ReadonlyArray<SchemaReportFinding>;
+} {
+ return { findings: buildSchemaReport(vault).findings };
+}
+
+export function buildSchemaGraph(vault: string): SchemaGraph {
+ const pack = loadSchemaPack(vault);
+ const nodes = new Map<string, SchemaGraphNode>();
+ const edges: SchemaGraphEdge[] = [];
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ const builtin = new Set(DEFAULT_SCHEMA_VOCAB[category]);
+ for (const token of pack.vocabulary[category]) {
+ nodes.set(token, {
+ id: token,
+ kind: "type",
+ category,
+ builtin: builtin.has(token),
+ });
+ }
+ }
+ for (const token of pack.link_types) {
+ nodes.set(`link:${token}`, { id: `link:${token}`, kind: "link_type" });
+ }
+ for (const [token, aliases] of Object.entries(pack.aliases)) {
+ for (const alias of aliases) {
+ nodes.set(alias, nodes.get(alias) ?? { id: alias, kind: "type" });
+ edges.push({ from: alias, to: token, kind: "alias" });
+ }
+ }
+ for (const [prefix, token] of Object.entries(pack.prefixes)) {
+ edges.push({ from: prefix, to: token, kind: "prefix" });
+ }
+ for (const token of pack.extractable) {
+ edges.push({ from: token, to: token, kind: "extractable" });
+ }
+ for (const [token, expert] of Object.entries(pack.expert_routing)) {
+ nodes.set(`expert:${expert}`, { id: expert, kind: "expert" });
+ edges.push({ from: token, to: expert, kind: "expert_routing" });
+ }
+ return {
+ nodes: [...nodes.values()].toSorted((left, right) => left.id.localeCompare(right.id)),
+ edges: edges.toSorted(
+ (left, right) =>
+ left.kind.localeCompare(right.kind) ||
+ left.from.localeCompare(right.from) ||
+ left.to.localeCompare(right.to),
+ ),
+ };
+}
+
+export function explainSchemaToken(vault: string, rawToken: string): SchemaExplanation {
+ const token = normalizeSchemaToken(rawToken);
+ const pack = loadSchemaPack(vault);
+ const report = buildSchemaReport(vault);
+ const categories = SCHEMA_VOCAB_CATEGORIES.filter((category) =>
+ pack.vocabulary[category].includes(token),
+ );
+ const declared = SCHEMA_VOCAB_CATEGORIES.filter((category) =>
+ (pack.declarations[category] ?? []).includes(token),
+ );
+ const builtin = SCHEMA_VOCAB_CATEGORIES.filter((category) =>
+ DEFAULT_SCHEMA_VOCAB[category].includes(token),
+ );
+ const usage = emptyCounts();
+ for (const category of SCHEMA_VOCAB_CATEGORIES)
+ usage[category] = usageCount(report, category, token);
+ return {
+ token,
+ categories,
+ declared,
+ builtin,
+ usage,
+ aliases: pack.aliases[token] ?? [],
+ prefixes: Object.entries(pack.prefixes)
+ .filter(([, value]) => value === token)
+ .map(([prefix]) => prefix)
+ .toSorted(),
+ link_type: pack.link_types.includes(token),
+ extractable: pack.extractable.includes(token),
+ expert: pack.expert_routing[token] ?? null,
+ };
+}
+
+export function reviewSchemaOrphans(vault: string): SchemaOrphanReport {
+ return {
+ orphans: buildSchemaReport(vault).findings.filter(
+ (finding) => finding.kind === "unused-declaration",
+ ),
+ };
+}
+
+export async function applySchemaAdminMutations(
+ vault: string,
+ mutations: ReadonlyArray<SchemaMutation>,
+ opts: { actor: string; reason?: string },
+): Promise<ApplySchemaMutationsResult> {
+ return await applySchemaMutations(vault, mutations, opts);
+}
+
+export function buildSchemaSyncResult(
+ opts: { dryRun?: boolean; batchSize?: number } = {},
+): SchemaSyncResult {
+ return {
+ dry_run: opts.dryRun ?? true,
+ batch_size: opts.batchSize ?? 100,
+ updated: 0,
+ skipped: 0,
+ note: "schema_type metadata is already stored in vault files; no backfill was required",
+ };
+}
+
+export function parseSchemaMutationPayloads(payloads: ReadonlyArray<string>): SchemaMutation[] {
+ const out: SchemaMutation[] = [];
+ for (const payload of payloads) {
+ const parsed = JSON.parse(payload) as unknown;
+ if (Array.isArray(parsed)) {
+ for (const item of parsed) out.push(coerceSchemaMutation(item));
+ } else {
+ out.push(coerceSchemaMutation(parsed));
+ }
+ }
+ return out;
+}
+
+export function coerceSchemaMutations(value: unknown): SchemaMutation[] {
+ if (!Array.isArray(value)) throw new Error("mutations must be an array");
+ return value.map(coerceSchemaMutation);
+}
+
+function coerceSchemaMutation(value: unknown): SchemaMutation {
+ if (!isRecord(value)) throw new Error("schema mutation must be an object");
+ const op = readString(value, "op");
+ switch (op) {
+ case "add_type":
+ case "remove_type":
+ return {
+ op,
+ category: readCategory(value),
+ token: readString(value, "token"),
+ };
+ case "update_type":
+ return {
+ op,
+ category: readCategory(value),
+ token: readString(value, "token"),
+ new_token: readString(value, "new_token"),
+ };
+ case "add_alias":
+ case "remove_alias":
+ return {
+ op,
+ token: readString(value, "token"),
+ alias: readString(value, "alias"),
+ };
+ case "add_prefix":
+ return {
+ op,
+ prefix: readString(value, "prefix"),
+ token: readString(value, "token"),
+ };
+ case "remove_prefix":
+ return { op, prefix: readString(value, "prefix") };
+ case "add_link_type":
+ case "remove_link_type":
+ return { op, token: readString(value, "token") };
+ case "set_extractable":
+ return {
+ op,
+ token: readString(value, "token"),
+ enabled: readBoolean(value, "enabled"),
+ };
+ case "set_expert_routing": {
+ const expert = value["expert"];
+ if (expert !== null && typeof expert !== "string")
+ throw new Error("mutation.expert must be a string or null");
+ return { op, token: readString(value, "token"), expert };
+ }
+ default:
+ throw new Error(`unsupported schema mutation op: ${op}`);
+ }
+}
+
+function readCategory(value: Record<string, unknown>): SchemaVocabularyCategory {
+ const raw = readString(value, "category");
+ if (!(SCHEMA_VOCAB_CATEGORIES as ReadonlyArray<string>).includes(raw)) {
+ throw new Error(`mutation.category must be one of ${SCHEMA_VOCAB_CATEGORIES.join(", ")}`);
+ }
+ return raw as SchemaVocabularyCategory;
+}
+
+function readString(value: Record<string, unknown>, key: string): string {
+ const raw = value[key];
+ if (typeof raw !== "string" || raw.trim() === "")
+ throw new Error(`mutation.${key} must be a non-empty string`);
+ return raw;
+}
+
+function readBoolean(value: Record<string, unknown>, key: string): boolean {
+ const raw = value[key];
+ if (typeof raw !== "boolean") throw new Error(`mutation.${key} must be a boolean`);
+ return raw;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function emptyCounts(): Record<SchemaVocabularyCategory, number> {
+ return {
+ preference_types: 0,
+ signal_types: 0,
+ page_types: 0,
+ log_event_kinds: 0,
+ };
+}
+
+function sumUsage(report: BrainSchemaReport, category: SchemaVocabularyCategory): number {
+ return report.usage[category].reduce((sum, item) => sum + item.count, 0);
+}
+
+function usageCount(
+ report: BrainSchemaReport,
+ category: SchemaVocabularyCategory,
+ token: string,
+): number {
+ return report.usage[category].find((item) => item.token === token)?.count ?? 0;
+}
diff --git a/src/core/brain/schema-mutate.ts b/src/core/brain/schema-mutate.ts
new file mode 100644
index 00000000..375bcd04
--- /dev/null
+++ b/src/core/brain/schema-mutate.ts
@@ -0,0 +1,325 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendAuditRecord } from "../reliability/audit.ts";
+import { atomicWriteText } from "../reliability/atomic.ts";
+import { withFileLock } from "../reliability/lock.ts";
+import { brainConfigPath, brainDirs } from "./paths.ts";
+import {
+ parseSchemaPack,
+ renderSchemaBlock,
+ replaceSchemaBlock,
+ schemaPackTokens,
+ type SchemaPack,
+} from "./schema-pack.ts";
+import {
+ SCHEMA_VOCAB_CATEGORIES,
+ validateSchemaDeclarations,
+ validateSchemaToken,
+ type BrainSchemaDeclarations,
+ type SchemaVocabularyCategory,
+} from "./schema-vocab.ts";
+
+export type SchemaMutation =
+ | {
+ readonly op: "add_type" | "remove_type";
+ readonly category: SchemaVocabularyCategory;
+ readonly token: string;
+ }
+ | {
+ readonly op: "update_type";
+ readonly category: SchemaVocabularyCategory;
+ readonly token: string;
+ readonly new_token: string;
+ }
+ | {
+ readonly op: "add_alias" | "remove_alias";
+ readonly token: string;
+ readonly alias: string;
+ }
+ | {
+ readonly op: "add_prefix";
+ readonly prefix: string;
+ readonly token: string;
+ }
+ | { readonly op: "remove_prefix"; readonly prefix: string }
+ | {
+ readonly op: "add_link_type" | "remove_link_type";
+ readonly token: string;
+ }
+ | {
+ readonly op: "set_extractable";
+ readonly token: string;
+ readonly enabled: boolean;
+ }
+ | {
+ readonly op: "set_expert_routing";
+ readonly token: string;
+ readonly expert: string | null;
+ };
+
+export interface ApplySchemaMutationsOptions {
+ readonly actor: string;
+ readonly now?: Date;
+ readonly reason?: string;
+ readonly lockStaleMs?: number;
+}
+
+export interface ApplySchemaMutationsResult {
+ readonly applied: number;
+ readonly audit_path: string;
+ readonly pack: SchemaPack;
+}
+
+interface MutableSchemaPack {
+ declarations: Record<SchemaVocabularyCategory, string[]>;
+ aliases: Record<string, string[]>;
+ prefixes: Record<string, string>;
+ link_types: string[];
+ extractable: string[];
+ expert_routing: Record<string, string>;
+}
+
+export async function applySchemaMutations(
+ vault: string,
+ mutations: ReadonlyArray<SchemaMutation>,
+ opts: ApplySchemaMutationsOptions,
+): Promise<ApplySchemaMutationsResult> {
+ const configPath = brainConfigPath(vault);
+ const now = opts.now ?? new Date();
+ return await withFileLock(configPath, { staleMs: opts.lockStaleMs ?? 30_000, retries: 3 }, () => {
+ const before = existsSync(configPath)
+ ? readFileSync(configPath, "utf8")
+ : "schema_version: 1\n";
+ const nextPack = applyMutationsToPack(parseSchemaPack(before), mutations);
+ const nextText = replaceSchemaBlock(before, renderSchemaBlock(nextPack));
+ atomicWriteText(configPath, nextText, {
+ validate: (candidate) => {
+ parseSchemaPack(candidate);
+ },
+ });
+ const auditPath = appendAuditRecord(join(brainDirs(vault).log, "schema-mutations"), {
+ timestamp: now.toISOString(),
+ actor: opts.actor,
+ action: "schema_apply_mutations",
+ target: "Brain/_brain.yaml",
+ ok: true,
+ details: {
+ applied: mutations.length,
+ mutations,
+ ...(opts.reason ? { reason: opts.reason } : {}),
+ },
+ });
+ return {
+ applied: mutations.length,
+ audit_path: auditPath,
+ pack: nextPack,
+ };
+ });
+}
+
+export function applyMutationsToPack(
+ pack: SchemaPack,
+ mutations: ReadonlyArray<SchemaMutation>,
+): SchemaPack {
+ const mutable = clonePack(pack);
+ for (const mutation of mutations) {
+ applyOne(mutable, mutation);
+ }
+ const next = freezeMutable(mutable);
+ validateSchemaPackReferences(next);
+ return next;
+}
+
+function applyOne(pack: MutableSchemaPack, mutation: SchemaMutation): void {
+ switch (mutation.op) {
+ case "add_type": {
+ const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
+ addUnique(pack.declarations[mutation.category], token);
+ return;
+ }
+ case "remove_type": {
+ const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
+ removeValue(pack.declarations[mutation.category], token);
+ delete pack.aliases[token];
+ for (const [prefix, target] of Object.entries(pack.prefixes)) {
+ if (target === token) delete pack.prefixes[prefix];
+ }
+ removeValue(pack.extractable, token);
+ delete pack.expert_routing[token];
+ return;
+ }
+ case "update_type": {
+ const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
+ const next = validateSchemaToken(mutation.new_token, `schema.${mutation.category}`);
+ replaceDeclaredValue(pack.declarations[mutation.category], token, next, mutation.category);
+ if (pack.aliases[token]) {
+ pack.aliases[next] = pack.aliases[token]!;
+ delete pack.aliases[token];
+ }
+ for (const [prefix, target] of Object.entries(pack.prefixes)) {
+ if (target === token) pack.prefixes[prefix] = next;
+ }
+ replaceExistingValue(pack.extractable, token, next);
+ if (pack.expert_routing[token]) {
+ pack.expert_routing[next] = pack.expert_routing[token]!;
+ delete pack.expert_routing[token];
+ }
+ return;
+ }
+ case "add_alias": {
+ const token = validateSchemaToken(mutation.token, "schema.aliases");
+ const alias = validateSchemaToken(mutation.alias, `schema.aliases.${token}`);
+ pack.aliases[token] = pack.aliases[token] ?? [];
+ addUnique(pack.aliases[token]!, alias);
+ return;
+ }
+ case "remove_alias": {
+ const token = validateSchemaToken(mutation.token, "schema.aliases");
+ const alias = validateSchemaToken(mutation.alias, `schema.aliases.${token}`);
+ removeValue(pack.aliases[token] ?? [], alias);
+ if ((pack.aliases[token]?.length ?? 0) === 0) delete pack.aliases[token];
+ return;
+ }
+ case "add_prefix": {
+ const prefix = validateSchemaToken(mutation.prefix, "schema.prefixes");
+ const token = validateSchemaToken(mutation.token, `schema.prefixes.${prefix}`);
+ pack.prefixes[prefix] = token;
+ return;
+ }
+ case "remove_prefix": {
+ const prefix = validateSchemaToken(mutation.prefix, "schema.prefixes");
+ delete pack.prefixes[prefix];
+ return;
+ }
+ case "add_link_type": {
+ const token = validateSchemaToken(mutation.token, "schema.link_types");
+ addUnique(pack.link_types, token);
+ return;
+ }
+ case "remove_link_type": {
+ const token = validateSchemaToken(mutation.token, "schema.link_types");
+ removeValue(pack.link_types, token);
+ return;
+ }
+ case "set_extractable": {
+ const token = validateSchemaToken(mutation.token, "schema.extractable");
+ if (mutation.enabled) addUnique(pack.extractable, token);
+ else removeValue(pack.extractable, token);
+ return;
+ }
+ case "set_expert_routing": {
+ const token = validateSchemaToken(mutation.token, "schema.expert_routing");
+ const expert = mutation.expert?.trim() ?? "";
+ if (mutation.expert === null || expert === "") {
+ delete pack.expert_routing[token];
+ } else if (/[\r\n]/.test(mutation.expert)) {
+ throw new Error(`schema.expert_routing.${token}: expert must be a single line`);
+ } else {
+ pack.expert_routing[token] = expert;
+ }
+ return;
+ }
+ }
+}
+
+function clonePack(pack: SchemaPack): MutableSchemaPack {
+ return {
+ declarations: {
+ preference_types: [...(pack.declarations.preference_types ?? [])],
+ signal_types: [...(pack.declarations.signal_types ?? [])],
+ page_types: [...(pack.declarations.page_types ?? [])],
+ log_event_kinds: [...(pack.declarations.log_event_kinds ?? [])],
+ },
+ aliases: mapArrayRecord(pack.aliases),
+ prefixes: { ...pack.prefixes },
+ link_types: [...pack.link_types],
+ extractable: [...pack.extractable],
+ expert_routing: { ...pack.expert_routing },
+ };
+}
+
+function freezeMutable(input: MutableSchemaPack): SchemaPack {
+ const declarations = validateSchemaDeclarations(pruneDeclarations(input.declarations));
+ return parseSchemaPack(
+ renderSchemaBlock({
+ declarations,
+ vocabulary: {} as never,
+ aliases: freezeArrayRecord(input.aliases),
+ prefixes: Object.freeze({ ...input.prefixes }),
+ link_types: Object.freeze([...input.link_types]),
+ extractable: Object.freeze([...input.extractable]),
+ expert_routing: Object.freeze({ ...input.expert_routing }),
+ }),
+ );
+}
+
+function validateSchemaPackReferences(pack: SchemaPack): void {
+ const tokens = schemaPackTokens(pack);
+ for (const token of Object.keys(pack.aliases)) {
+ if (!tokens.has(token)) throw new Error(`schema.aliases.${token}: token is not declared`);
+ }
+ for (const [prefix, token] of Object.entries(pack.prefixes)) {
+ if (!tokens.has(token)) throw new Error(`schema.prefixes.${prefix}: token is not declared`);
+ }
+ for (const token of pack.extractable) {
+ if (!tokens.has(token)) throw new Error(`schema.extractable.${token}: token is not declared`);
+ }
+ for (const token of Object.keys(pack.expert_routing)) {
+ if (!tokens.has(token)) {
+ throw new Error(`schema.expert_routing.${token}: token is not declared`);
+ }
+ }
+}
+
+function pruneDeclarations(
+ declarations: Record<SchemaVocabularyCategory, string[]>,
+): BrainSchemaDeclarations {
+ const out: Partial<Record<SchemaVocabularyCategory, ReadonlyArray<string>>> = {};
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ const values = declarations[category];
+ if (values.length > 0) out[category] = values;
+ }
+ return out as BrainSchemaDeclarations;
+}
+
+function mapArrayRecord(
+ record: Readonly<Record<string, ReadonlyArray<string>>>,
+): Record<string, string[]> {
+ const out: Record<string, string[]> = {};
+ for (const [key, values] of Object.entries(record)) out[key] = [...values];
+ return out;
+}
+
+function freezeArrayRecord(
+ record: Record<string, string[]>,
+): Readonly<Record<string, ReadonlyArray<string>>> {
+ const out: Record<string, ReadonlyArray<string>> = {};
+ for (const [key, values] of Object.entries(record)) out[key] = Object.freeze([...values]);
+ return Object.freeze(out);
+}
+
+function addUnique(values: string[], token: string): void {
+ if (!values.includes(token)) values.push(token);
+}
+
+function removeValue(values: string[], token: string): void {
+ const index = values.indexOf(token);
+ if (index >= 0) values.splice(index, 1);
+}
+
+function replaceDeclaredValue(
+ values: string[],
+ token: string,
+ next: string,
+ category: SchemaVocabularyCategory,
+): void {
+ const index = values.indexOf(token);
+ if (index < 0) throw new Error(`schema.${category}: ${token} is not declared`);
+ values[index] = next;
+}
+
+function replaceExistingValue(values: string[], token: string, next: string): void {
+ const index = values.indexOf(token);
+ if (index >= 0) values[index] = next;
+}
diff --git a/src/core/brain/schema-pack.ts b/src/core/brain/schema-pack.ts
new file mode 100644
index 00000000..c9c27d1b
--- /dev/null
+++ b/src/core/brain/schema-pack.ts
@@ -0,0 +1,306 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { brainConfigPath } from "./paths.ts";
+import {
+ SCHEMA_VOCAB_CATEGORIES,
+ resolveSchemaVocabulary,
+ validateSchemaDeclarations,
+ validateSchemaToken,
+ type BrainSchemaDeclarations,
+ type BrainSchemaVocabulary,
+ type SchemaVocabularyCategory,
+} from "./schema-vocab.ts";
+
+export interface SchemaPack {
+ readonly declarations: BrainSchemaDeclarations;
+ readonly vocabulary: BrainSchemaVocabulary;
+ readonly aliases: Readonly<Record<string, ReadonlyArray<string>>>;
+ readonly prefixes: Readonly<Record<string, string>>;
+ readonly link_types: ReadonlyArray<string>;
+ readonly extractable: ReadonlyArray<string>;
+ readonly expert_routing: Readonly<Record<string, string>>;
+}
+
+export function loadSchemaPack(vault: string): SchemaPack {
+ const path = brainConfigPath(vault);
+ const text = existsSync(path) ? readFileSync(path, "utf8") : "schema_version: 1\n";
+ return parseSchemaPack(text);
+}
+
+export function parseSchemaPack(configText: string): SchemaPack {
+ const lines = extractSchemaLines(configText);
+ const partial: Partial<Record<SchemaVocabularyCategory, ReadonlyArray<string>>> = {};
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ const values = parseListField(lines, category);
+ if (values.length > 0) partial[category] = values;
+ }
+ const declarations = validateSchemaDeclarations(partial);
+ const aliases = parseMapListField(lines, "aliases", "schema.aliases");
+ const prefixes = parseMapScalarField(lines, "prefixes", "schema.prefixes");
+ const linkTypes = parseListField(lines, "link_types").map((token, index) =>
+ validateSchemaToken(token, `schema.link_types[${index}]`),
+ );
+ const extractable = parseListField(lines, "extractable").map((token, index) =>
+ validateSchemaToken(token, `schema.extractable[${index}]`),
+ );
+ const expertRouting = parseMapScalarField(
+ lines,
+ "expert_routing",
+ "schema.expert_routing",
+ false,
+ );
+
+ return freezeSchemaPack({
+ declarations,
+ vocabulary: resolveSchemaVocabulary(declarations),
+ aliases,
+ prefixes,
+ link_types: unique(linkTypes),
+ extractable: unique(extractable),
+ expert_routing: expertRouting,
+ });
+}
+
+export function renderSchemaBlock(pack: SchemaPack): string {
+ const lines = ["schema:"];
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ const values = pack.declarations[category] ?? [];
+ if (values.length === 0) continue;
+ lines.push(` ${category}:`);
+ for (const token of values) lines.push(` - ${token}`);
+ }
+ renderMapList(lines, "aliases", pack.aliases);
+ renderMapScalar(lines, "prefixes", pack.prefixes);
+ renderList(lines, "link_types", pack.link_types);
+ renderList(lines, "extractable", pack.extractable);
+ renderMapScalar(lines, "expert_routing", pack.expert_routing);
+ if (lines.length === 1) lines.push(" {}");
+ return lines.join("\n") + "\n";
+}
+
+export function replaceSchemaBlock(configText: string, schemaBlock: string): string {
+ const normalized = configText.endsWith("\n") ? configText : configText + "\n";
+ const lines = normalized.split("\n");
+ const start = lines.findIndex((line) => /^schema:\s*$/.test(line));
+ if (start < 0) return normalized + schemaBlock;
+
+ let end = start + 1;
+ while (end < lines.length) {
+ const line = lines[end]!;
+ if (line.length > 0 && !line.startsWith(" ") && !line.startsWith("\t")) break;
+ end++;
+ }
+ const before = lines.slice(0, start).join("\n");
+ const after = lines.slice(end).join("\n").replace(/^\n+/, "");
+ return [before, schemaBlock.trimEnd(), after].filter((part) => part.length > 0).join("\n") + "\n";
+}
+
+export function schemaPackTokens(pack: SchemaPack): ReadonlySet<string> {
+ const tokens = new Set<string>();
+ for (const category of SCHEMA_VOCAB_CATEGORIES) {
+ for (const token of pack.vocabulary[category]) tokens.add(token);
+ }
+ for (const token of pack.link_types) tokens.add(token);
+ return tokens;
+}
+
+function extractSchemaLines(configText: string): string[] {
+ const all = configText.split(/\r?\n/);
+ const start = all.findIndex((line) => /^schema:\s*$/.test(line));
+ if (start < 0) return [];
+ const out: string[] = [];
+ for (let index = start + 1; index < all.length; index++) {
+ const line = all[index]!;
+ if (line.length > 0 && !line.startsWith(" ") && !line.startsWith("\t")) break;
+ out.push(line);
+ }
+ return out;
+}
+
+function parseListField(lines: ReadonlyArray<string>, key: string): string[] {
+ const start = findField(lines, key);
+ if (start < 0) return [];
+ const rest = fieldRest(lines[start]!, key);
+ if (rest.startsWith("[")) return parseInlineList(rest);
+ if (rest === "{}") return [];
+
+ const values: string[] = [];
+ for (let index = start + 1; index < lines.length; index++) {
+ const line = lines[index]!;
+ if (/^ \S/.test(line)) break;
+ const match = /^ -\s+(.+?)\s*$/.exec(line);
+ if (match) values.push(stripQuotes(match[1]!));
+ }
+ return values;
+}
+
+function parseMapListField(
+ lines: ReadonlyArray<string>,
+ key: string,
+ field: string,
+): Record<string, ReadonlyArray<string>> {
+ const start = findField(lines, key);
+ if (start < 0) return {};
+ const out: Record<string, string[]> = {};
+ for (let index = start + 1; index < lines.length; index++) {
+ const line = lines[index]!;
+ if (/^ \S/.test(line)) break;
+ const flat = /^ -\s+(.+?)\s*$/.exec(line);
+ if (flat) {
+ const [rawToken, rawAlias] = splitPair(flat[1]!);
+ const token = validateSchemaToken(rawToken, `${field}.${rawToken}`);
+ const alias = validateSchemaToken(rawAlias, `${field}.${token}`);
+ out[token] = out[token] ?? [];
+ out[token]!.push(alias);
+ continue;
+ }
+ const entry = /^ ([^:]+):\s*(.*)$/.exec(line);
+ if (!entry) continue;
+ const token = validateSchemaToken(stripQuotes(entry[1]!), `${field}.${entry[1]}`);
+ const rest = entry[2]!.trim();
+ const values = rest.startsWith("[") ? parseInlineList(rest) : collectNestedList(lines, index);
+ out[token] = unique(
+ values.map((value, valueIndex) =>
+ validateSchemaToken(value, `${field}.${token}[${valueIndex}]`),
+ ),
+ );
+ }
+ return freezeRecord(out);
+}
+
+function parseMapScalarField(
+ lines: ReadonlyArray<string>,
+ key: string,
+ field: string,
+ validateValue = true,
+): Record<string, string> {
+ const start = findField(lines, key);
+ if (start < 0) return {};
+ const out: Record<string, string> = {};
+ for (let index = start + 1; index < lines.length; index++) {
+ const line = lines[index]!;
+ if (/^ \S/.test(line)) break;
+ const flat = /^ -\s+(.+?)\s*$/.exec(line);
+ if (flat) {
+ const [rawName, rawValue] = splitPair(flat[1]!);
+ const name = validateSchemaToken(rawName, `${field}.${rawName}`);
+ out[name] = validateValue
+ ? validateSchemaToken(rawValue, `${field}.${name}`)
+ : rawValue.trim();
+ continue;
+ }
+ const entry = /^ ([^:]+):\s*(.+?)\s*$/.exec(line);
+ if (!entry) continue;
+ const name = validateSchemaToken(stripQuotes(entry[1]!), `${field}.${entry[1]}`);
+ const rawValue = stripQuotes(entry[2]!);
+ out[name] = validateValue ? validateSchemaToken(rawValue, `${field}.${name}`) : rawValue.trim();
+ }
+ return freezeRecord(out);
+}
+
+function collectNestedList(lines: ReadonlyArray<string>, start: number): string[] {
+ const values: string[] = [];
+ for (let index = start + 1; index < lines.length; index++) {
+ const line = lines[index]!;
+ if (/^ \S/.test(line) || /^ \S/.test(line)) break;
+ const match = /^ -\s+(.+?)\s*$/.exec(line);
+ if (match) values.push(stripQuotes(match[1]!));
+ }
+ return values;
+}
+
+function findField(lines: ReadonlyArray<string>, key: string): number {
+ return lines.findIndex((line) => new RegExp(`^ ${escapeRegex(key)}:\\s*`).test(line));
+}
+
+function fieldRest(line: string, key: string): string {
+ return line.replace(new RegExp(`^ ${escapeRegex(key)}:\\s*`), "").trim();
+}
+
+function parseInlineList(raw: string): string[] {
+ const trimmed = raw.trim();
+ if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return [];
+ const inner = trimmed.slice(1, -1).trim();
+ if (inner.length === 0) return [];
+ return inner.split(",").map((item) => stripQuotes(item));
+}
+
+function stripQuotes(raw: string): string {
+ const trimmed = raw.trim();
+ if (
+ (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+ (trimmed.startsWith("'") && trimmed.endsWith("'"))
+ ) {
+ return trimmed.slice(1, -1).trim();
+ }
+ return trimmed;
+}
+
+function renderList(lines: string[], key: string, values: ReadonlyArray<string>): void {
+ if (values.length === 0) return;
+ lines.push(` ${key}:`);
+ for (const value of values) lines.push(` - ${value}`);
+}
+
+function renderMapList(
+ lines: string[],
+ key: string,
+ values: Readonly<Record<string, ReadonlyArray<string>>>,
+): void {
+ const entries = Object.entries(values).toSorted(([left], [right]) => left.localeCompare(right));
+ if (entries.length === 0) return;
+ lines.push(` ${key}:`);
+ for (const [token, aliases] of entries) {
+ for (const alias of aliases) lines.push(` - ${token}=${alias}`);
+ }
+}
+
+function renderMapScalar(
+ lines: string[],
+ key: string,
+ values: Readonly<Record<string, string>>,
+): void {
+ const entries = Object.entries(values).toSorted(([left], [right]) => left.localeCompare(right));
+ if (entries.length === 0) return;
+ lines.push(` ${key}:`);
+ for (const [name, value] of entries) lines.push(` - ${name}=${value}`);
+}
+
+function splitPair(raw: string): [string, string] {
+ const index = raw.indexOf("=");
+ if (index < 0) return [raw, ""];
+ return [raw.slice(0, index).trim(), raw.slice(index + 1).trim()];
+}
+
+function freezeSchemaPack(
+ input: Omit<SchemaPack, "vocabulary"> & { vocabulary: BrainSchemaVocabulary },
+): SchemaPack {
+ return Object.freeze({
+ declarations: input.declarations,
+ vocabulary: input.vocabulary,
+ aliases: input.aliases,
+ prefixes: input.prefixes,
+ link_types: Object.freeze([...input.link_types]),
+ extractable: Object.freeze([...input.extractable]),
+ expert_routing: input.expert_routing,
+ });
+}
+
+function freezeRecord<T>(record: Record<string, T>): Readonly<Record<string, T>> {
+ return Object.freeze({ ...record });
+}
+
+function unique(values: ReadonlyArray<string>): string[] {
+ const seen = new Set<string>();
+ const out: string[] = [];
+ for (const value of values) {
+ if (seen.has(value)) continue;
+ seen.add(value);
+ out.push(value);
+ }
+ return out;
+}
+
+function escapeRegex(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
diff --git a/src/core/brain/session-lifecycle.ts b/src/core/brain/session-lifecycle.ts
new file mode 100644
index 00000000..435edb7e
--- /dev/null
+++ b/src/core/brain/session-lifecycle.ts
@@ -0,0 +1,272 @@
+import { join } from "node:path";
+
+import { appendAuditRecord } from "../reliability/audit.ts";
+import { appendLogEvent } from "./log.ts";
+import { brainDirs } from "./paths.ts";
+import { buildDedupIndex, computeDedupHash, type DedupIndexEntry } from "./dedup-hash.ts";
+import { discoverMarkersDetailed } from "./inline.ts";
+import { writeSignal } from "./signal.ts";
+import { isoDate, isoSecond } from "./time.ts";
+import { BRAIN_LOG_EVENT_KIND, BRAIN_SIGNAL_SOURCE_TYPE } from "./types.ts";
+import { validateBrainFeedbackInput } from "./sessions/validate-feedback.ts";
+
+export interface CaptureSessionLifecycleOptions {
+ readonly agent: string;
+ readonly now?: Date;
+ readonly dryRun?: boolean;
+}
+
+export interface CaptureSessionLifecycleResult {
+ readonly event: string;
+ readonly session_id?: string;
+ readonly signals_created: number;
+ readonly signals_deduped: number;
+ readonly tool_replays: number;
+ readonly malformed: number;
+ readonly audit_path: string;
+ readonly log_path?: string;
+}
+
+interface NormalizedPayload {
+ readonly event: string;
+ readonly sessionId?: string;
+ readonly promptText?: string;
+ readonly toolName?: string;
+ readonly toolInput?: unknown;
+ readonly malformed: number;
+}
+
+export async function captureSessionLifecycleEvent(
+ vault: string,
+ payload: unknown,
+ opts: CaptureSessionLifecycleOptions,
+): Promise<CaptureSessionLifecycleResult> {
+ const now = opts.now ?? new Date();
+ const normalized = normalizePayload(payload);
+ let dedup: Map<string, DedupIndexEntry> | undefined;
+ const ensureDedup = (): Map<string, DedupIndexEntry> => {
+ dedup ??= buildDedupIndex(vault);
+ return dedup;
+ };
+ const counters = {
+ signals_created: 0,
+ signals_deduped: 0,
+ tool_replays: 0,
+ malformed: normalized.malformed,
+ };
+
+ if (normalized.promptText !== undefined) {
+ captureMarkers(vault, normalized, normalized.promptText, opts, now, ensureDedup(), counters);
+ }
+
+ if (normalized.toolName === "brain_feedback") {
+ captureToolFeedback(vault, normalized, opts, now, ensureDedup(), counters);
+ }
+
+ let logPath: string | undefined;
+ if (!opts.dryRun) {
+ logPath = appendLifecycleLog(vault, normalized, opts.agent, now, counters);
+ }
+
+ const auditPath = appendAuditRecord(join(brainDirs(vault).log, "session-lifecycle"), {
+ timestamp: now.toISOString(),
+ actor: opts.agent,
+ action: "session_lifecycle_capture",
+ target: "Brain/session-lifecycle",
+ ok: true,
+ details: {
+ event: normalized.event,
+ ...(normalized.sessionId ? { session_id: normalized.sessionId } : {}),
+ dry_run: opts.dryRun === true,
+ ...counters,
+ },
+ });
+
+ return {
+ event: normalized.event,
+ ...(normalized.sessionId ? { session_id: normalized.sessionId } : {}),
+ signals_created: counters.signals_created,
+ signals_deduped: counters.signals_deduped,
+ tool_replays: counters.tool_replays,
+ malformed: counters.malformed,
+ audit_path: auditPath,
+ ...(logPath ? { log_path: logPath } : {}),
+ };
+}
+
+function normalizePayload(payload: unknown): NormalizedPayload {
+ if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+ return { event: "unknown", malformed: 1 };
+ }
+ const record = payload as Record<string, unknown>;
+ const event =
+ readNonEmptyString(record["hook_event_name"]) ??
+ readNonEmptyString(record["event"]) ??
+ "unknown";
+ const sessionId = readNonEmptyString(record["session_id"]);
+ return {
+ event,
+ ...(sessionId ? { sessionId } : {}),
+ ...(extractPromptText(record) ? { promptText: extractPromptText(record)! } : {}),
+ ...(readNonEmptyString(record["tool_name"])
+ ? { toolName: readNonEmptyString(record["tool_name"])! }
+ : {}),
+ ...("tool_input" in record ? { toolInput: record["tool_input"] } : {}),
+ malformed: 0,
+ };
+}
+
+function extractPromptText(record: Record<string, unknown>): string | undefined {
+ const direct = readNonEmptyString(record["prompt"]);
+ if (direct) return direct;
+ const message = record["message"];
+ if (typeof message === "string" && message.trim().length > 0) return message;
+ if (message !== null && typeof message === "object") {
+ const content = (message as Record<string, unknown>)["content"];
+ if (typeof content === "string" && content.trim().length > 0) return content;
+ }
+ return undefined;
+}
+
+function captureMarkers(
+ vault: string,
+ payload: NormalizedPayload,
+ text: string,
+ opts: CaptureSessionLifecycleOptions,
+ now: Date,
+ dedup: Map<string, DedupIndexEntry>,
+ counters: MutableCounters,
+): void {
+ const discovery = discoverMarkersDetailed(text);
+ counters.malformed += discovery.malformed;
+ for (const marker of discovery.markers) {
+ const dedupHash = computeDedupHash({
+ topic: marker.topic,
+ signal: marker.signal,
+ principle: marker.principle,
+ ...(marker.scope ? { scope: marker.scope } : {}),
+ });
+ emitSignal(vault, payload, opts, now, dedup, counters, {
+ topic: marker.topic,
+ signal: marker.signal,
+ principle: marker.principle,
+ ...(marker.scope ? { scope: marker.scope } : {}),
+ agent: marker.agent ?? opts.agent,
+ ...(marker.note ? { raw: marker.note } : {}),
+ dedupHash,
+ });
+ }
+}
+
+function captureToolFeedback(
+ vault: string,
+ payload: NormalizedPayload,
+ opts: CaptureSessionLifecycleOptions,
+ now: Date,
+ dedup: Map<string, DedupIndexEntry>,
+ counters: MutableCounters,
+): void {
+ const validated = validateBrainFeedbackInput(payload.toolInput);
+ if (!validated.ok) {
+ counters.malformed++;
+ return;
+ }
+ counters.tool_replays++;
+ const input = validated.value;
+ const dedupHash = computeDedupHash({
+ topic: input.topic,
+ signal: input.signal,
+ principle: input.principle,
+ ...(input.scope ? { scope: input.scope } : {}),
+ });
+ emitSignal(vault, payload, opts, now, dedup, counters, {
+ topic: input.topic,
+ signal: input.signal,
+ principle: input.principle,
+ ...(input.scope ? { scope: input.scope } : {}),
+ agent: input.agent ?? opts.agent,
+ ...(input.raw ? { raw: input.raw } : {}),
+ dedupHash,
+ });
+}
+
+interface SignalPayload {
+ readonly topic: string;
+ readonly signal: "positive" | "negative";
+ readonly principle: string;
+ readonly scope?: string;
+ readonly agent: string;
+ readonly raw?: string;
+ readonly dedupHash: string;
+}
+
+interface MutableCounters {
+ signals_created: number;
+ signals_deduped: number;
+ tool_replays: number;
+ malformed: number;
+}
+
+function emitSignal(
+ vault: string,
+ payload: NormalizedPayload,
+ opts: CaptureSessionLifecycleOptions,
+ now: Date,
+ dedup: Map<string, DedupIndexEntry>,
+ counters: MutableCounters,
+ signal: SignalPayload,
+): void {
+ if (dedup.has(signal.dedupHash)) {
+ counters.signals_deduped++;
+ return;
+ }
+ if (opts.dryRun) return;
+ const sessionRef = sessionReference(payload);
+ const result = writeSignal(vault, {
+ topic: signal.topic,
+ signal: signal.signal,
+ agent: signal.agent,
+ principle: signal.principle,
+ created_at: isoSecond(now),
+ date: isoDate(now),
+ slug: signal.topic,
+ ...(signal.scope ? { scope: signal.scope } : {}),
+ source: [`[[${sessionRef}]]`],
+ source_type: BRAIN_SIGNAL_SOURCE_TYPE.session,
+ dedup_hash: signal.dedupHash,
+ session_ref: sessionRef,
+ ...(signal.raw ? { raw: signal.raw } : {}),
+ });
+ dedup.set(signal.dedupHash, { id: result.id, path: result.path });
+ counters.signals_created++;
+}
+
+function appendLifecycleLog(
+ vault: string,
+ payload: NormalizedPayload,
+ agent: string,
+ now: Date,
+ counters: MutableCounters,
+): string {
+ return appendLogEvent(vault, {
+ timestamp: isoSecond(now),
+ eventType: BRAIN_LOG_EVENT_KIND.sessionLifecycle,
+ body: {
+ agent,
+ event: payload.event,
+ ...(payload.sessionId ? { session_id: payload.sessionId } : {}),
+ signals_created: String(counters.signals_created),
+ signals_deduped: String(counters.signals_deduped),
+ tool_replays: String(counters.tool_replays),
+ malformed: String(counters.malformed),
+ },
+ }).logPath;
+}
+
+function sessionReference(payload: NormalizedPayload): string {
+ return `session:${payload.sessionId ?? "unknown"}#${payload.event}`;
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
diff --git a/src/core/brain/types.ts b/src/core/brain/types.ts
index 86c48479..ebac9031 100644
--- a/src/core/brain/types.ts
+++ b/src/core/brain/types.ts
@@ -22,8 +22,7 @@ export const BRAIN_SIGNAL_SIGN = {
positive: "positive",
negative: "negative",
} as const;
-export type BrainSignalSign =
- (typeof BRAIN_SIGNAL_SIGN)[keyof typeof BRAIN_SIGNAL_SIGN];
+export type BrainSignalSign = (typeof BRAIN_SIGNAL_SIGN)[keyof typeof BRAIN_SIGNAL_SIGN];
/**
* Where the signal came from (Β§9 / Β§16 capture extensions). Absent
@@ -48,12 +47,9 @@ const BRAIN_SIGNAL_SOURCE_TYPE_VALUES: ReadonlyArray<BrainSignalSourceType> =
Object.values(BRAIN_SIGNAL_SOURCE_TYPE);
/** Type-guard for the enum union β€” used by writer + parser. */
-export function isBrainSignalSourceType(
- v: unknown,
-): v is BrainSignalSourceType {
+export function isBrainSignalSourceType(v: unknown): v is BrainSignalSourceType {
return (
- typeof v === "string" &&
- (BRAIN_SIGNAL_SOURCE_TYPE_VALUES as ReadonlyArray<string>).includes(v)
+ typeof v === "string" && (BRAIN_SIGNAL_SOURCE_TYPE_VALUES as ReadonlyArray<string>).includes(v)
);
}
@@ -78,8 +74,7 @@ export const BRAIN_CONFIDENCE = {
medium: "medium",
high: "high",
} as const;
-export type BrainConfidence =
- (typeof BRAIN_CONFIDENCE)[keyof typeof BRAIN_CONFIDENCE];
+export type BrainConfidence = (typeof BRAIN_CONFIDENCE)[keyof typeof BRAIN_CONFIDENCE];
export const BRAIN_MEMORY_LAYER = {
L0: "L0",
@@ -87,17 +82,13 @@ export const BRAIN_MEMORY_LAYER = {
L2: "L2",
L3: "L3",
} as const;
-export type BrainMemoryLayer =
- (typeof BRAIN_MEMORY_LAYER)[keyof typeof BRAIN_MEMORY_LAYER];
+export type BrainMemoryLayer = (typeof BRAIN_MEMORY_LAYER)[keyof typeof BRAIN_MEMORY_LAYER];
const BRAIN_MEMORY_LAYER_VALUES: ReadonlyArray<BrainMemoryLayer> =
Object.values(BRAIN_MEMORY_LAYER);
export function isBrainMemoryLayer(value: unknown): value is BrainMemoryLayer {
- return (
- typeof value === "string" &&
- BRAIN_MEMORY_LAYER_VALUES.includes(value as BrainMemoryLayer)
- );
+ return typeof value === "string" && BRAIN_MEMORY_LAYER_VALUES.includes(value as BrainMemoryLayer);
}
export const BRAIN_RETIRED_REASON = {
@@ -123,8 +114,7 @@ export const BRAIN_RETIRED_REASON = {
// no contradiction, the two rules said the same thing.
mergedInto: "merged-into",
} as const;
-export type BrainRetiredReason =
- (typeof BRAIN_RETIRED_REASON)[keyof typeof BRAIN_RETIRED_REASON];
+export type BrainRetiredReason = (typeof BRAIN_RETIRED_REASON)[keyof typeof BRAIN_RETIRED_REASON];
export const BRAIN_APPLY_RESULT = {
applied: "applied",
@@ -137,8 +127,7 @@ export const BRAIN_APPLY_RESULT = {
// `retain-pinned` log entry instead.
outdated: "outdated",
} as const;
-export type BrainApplyResult =
- (typeof BRAIN_APPLY_RESULT)[keyof typeof BRAIN_APPLY_RESULT];
+export type BrainApplyResult = (typeof BRAIN_APPLY_RESULT)[keyof typeof BRAIN_APPLY_RESULT];
/**
* All possible log event types. `dream` summarises a run; `feedback`
@@ -212,6 +201,12 @@ export const BRAIN_LOG_EVENT_KIND = {
* surface.
*/
note: "note",
+ /**
+ * `session-lifecycle` β€” runtime hook observation for session starts,
+ * prompt submits, tool uses, stops, and session ends. Payload carries
+ * event counters and never blocks the runtime.
+ */
+ sessionLifecycle: "session-lifecycle",
/**
* `reconcile` (Brain lifecycle suite, Feature 3) - the dream reconcile
* phase recorded a domain-classified contradiction. Payload carries
@@ -221,8 +216,7 @@ export const BRAIN_LOG_EVENT_KIND = {
*/
reconcile: "reconcile",
} as const;
-export type BrainLogEventKind =
- (typeof BRAIN_LOG_EVENT_KIND)[keyof typeof BRAIN_LOG_EVENT_KIND];
+export type BrainLogEventKind = (typeof BRAIN_LOG_EVENT_KIND)[keyof typeof BRAIN_LOG_EVENT_KIND];
/**
* Precomputed set of every event-kind string. Both the markdown
@@ -295,8 +289,7 @@ export const RECONCILE_DOMAIN = {
/** Resolvable by recency: one side is materially fresher. */
sourceFreshness: "source-freshness",
} as const;
-export type ReconcileDomain =
- (typeof RECONCILE_DOMAIN)[keyof typeof RECONCILE_DOMAIN];
+export type ReconcileDomain = (typeof RECONCILE_DOMAIN)[keyof typeof RECONCILE_DOMAIN];
/**
* An unresolved contradiction the reconcile phase surfaced for operator
@@ -660,9 +653,7 @@ export interface BrainSkipCorruptedLogEvent extends BrainLogEventBase {
/** `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 kind: typeof BRAIN_LOG_EVENT_KIND.pin | typeof BRAIN_LOG_EVENT_KIND.unpin;
readonly preference: string;
}
@@ -735,6 +726,17 @@ export interface BrainNoteLogEvent extends BrainLogEventBase {
readonly agent: string;
}
+export interface BrainSessionLifecycleLogEvent extends BrainLogEventBase {
+ readonly kind: typeof BRAIN_LOG_EVENT_KIND.sessionLifecycle;
+ readonly event: string;
+ readonly agent: string;
+ readonly signals_created: string;
+ readonly signals_deduped: string;
+ readonly tool_replays: string;
+ readonly malformed: string;
+ readonly session_id?: string;
+}
+
/** Discriminated union of every concrete log event type. */
export type BrainLogEvent =
| BrainDreamLogEvent
@@ -754,7 +756,8 @@ export type BrainLogEvent =
| BrainMergeLogEvent
| BrainUpgradeLogEvent
| BrainImportClaudeMemoryLogEvent
- | BrainNoteLogEvent;
+ | BrainNoteLogEvent
+ | BrainSessionLifecycleLogEvent;
// ----- Configuration (`Brain/_brain.yaml`) ----------------------------------
@@ -913,6 +916,11 @@ export interface BrainSchemaConfig {
readonly signal_types?: ReadonlyArray<string>;
readonly page_types?: ReadonlyArray<string>;
readonly log_event_kinds?: ReadonlyArray<string>;
+ readonly aliases?: ReadonlyArray<string>;
+ readonly prefixes?: ReadonlyArray<string>;
+ readonly link_types?: ReadonlyArray<string>;
+ readonly extractable?: ReadonlyArray<string>;
+ readonly expert_routing?: ReadonlyArray<string>;
}
/**
diff --git a/src/core/brain/watchdog.ts b/src/core/brain/watchdog.ts
new file mode 100644
index 00000000..3437d82b
--- /dev/null
+++ b/src/core/brain/watchdog.ts
@@ -0,0 +1,271 @@
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendAuditRecord, type AuditRecord } from "../reliability/audit.ts";
+import { buildProbeReport, type ProbeCheck, type ProbeReport } from "../reliability/probe.ts";
+import { resolveIndexPath } from "../search/paths.ts";
+import {
+ BRAIN_CONFIG_FILE,
+ BRAIN_INBOX_REL,
+ BRAIN_LOG_REL,
+ BRAIN_PREFERENCES_REL,
+ BRAIN_PROCESSED_REL,
+ BRAIN_RETIRED_REL,
+ brainConfigPath,
+ brainDirs,
+} from "./paths.ts";
+
+export interface WatchdogOptions {
+ readonly remediate?: boolean;
+ readonly dryRun?: boolean;
+ readonly restoreRunId?: string;
+ readonly forceRestore?: boolean;
+ readonly attempt?: number;
+ readonly now?: Date;
+}
+
+export interface WatchdogRemediation {
+ readonly action: "create-dir" | "run-command" | "restore-snapshot";
+ readonly target?: string;
+ readonly command?: string;
+ readonly safe: boolean;
+ readonly applied?: boolean;
+}
+
+export interface WatchdogRestoreState {
+ readonly requested: boolean;
+ readonly refused: boolean;
+ readonly run_id?: string;
+ readonly command?: string;
+ readonly reason?: string;
+}
+
+export interface WatchdogBackoff {
+ readonly attempt: number;
+ readonly base_delay_ms: number;
+ readonly next_delay_ms: number;
+ readonly max_delay_ms: number;
+}
+
+export interface BrainWatchdogResult {
+ readonly report: ProbeReport;
+ readonly remediation_plan: ReadonlyArray<WatchdogRemediation>;
+ readonly applied_remediations: ReadonlyArray<WatchdogRemediation>;
+ readonly restore: WatchdogRestoreState;
+ readonly backoff: WatchdogBackoff;
+ readonly audit_path: string;
+}
+
+const REQUIRED_DIRS: ReadonlyArray<{
+ rel: string;
+ pathKey: keyof ReturnType<typeof brainDirs>;
+}> = [
+ { rel: BRAIN_PREFERENCES_REL, pathKey: "preferences" },
+ { rel: BRAIN_RETIRED_REL, pathKey: "retired" },
+ { rel: BRAIN_INBOX_REL, pathKey: "inbox" },
+ { rel: BRAIN_PROCESSED_REL, pathKey: "processed" },
+ { rel: BRAIN_LOG_REL, pathKey: "log" },
+];
+
+export function runBrainWatchdog(vault: string, opts: WatchdogOptions = {}): BrainWatchdogResult {
+ const now = opts.now ?? new Date();
+ const checks: ProbeCheck[] = [];
+ const remediationPlan: WatchdogRemediation[] = [];
+ const applied: WatchdogRemediation[] = [];
+ const dirs = brainDirs(vault);
+
+ const configPath = brainConfigPath(vault);
+ const configKind = pathKind(configPath);
+ if (configKind === "file") {
+ checks.push({
+ name: "brain-config",
+ status: "ok",
+ message: `${BRAIN_CONFIG_FILE} exists`,
+ });
+ } else {
+ checks.push({
+ name: "brain-config",
+ status: "critical",
+ message:
+ configKind === "missing"
+ ? `${BRAIN_CONFIG_FILE} is missing`
+ : `${BRAIN_CONFIG_FILE} is not a file`,
+ remediation: "run o2b brain init",
+ });
+ remediationPlan.push({
+ action: "run-command",
+ command: "o2b brain init",
+ safe: false,
+ });
+ }
+
+ for (const dir of REQUIRED_DIRS) {
+ const abs = dirs[dir.pathKey];
+ const kind = pathKind(abs);
+ if (kind === "directory") {
+ checks.push({
+ name: `dir:${dir.rel}`,
+ status: "ok",
+ message: `${dir.rel} exists`,
+ });
+ continue;
+ }
+ checks.push({
+ name: `dir:${dir.rel}`,
+ status: "warning",
+ message: kind === "missing" ? `${dir.rel} is missing` : `${dir.rel} is not a directory`,
+ remediation: kind === "missing" ? `create ${dir.rel}` : `replace with directory ${dir.rel}`,
+ });
+ const remediation: WatchdogRemediation = {
+ action: "create-dir",
+ target: dir.rel,
+ safe: true,
+ };
+ remediationPlan.push(remediation);
+ if (opts.remediate && !opts.dryRun) {
+ if (kind !== "missing") rmSync(abs, { recursive: true, force: true });
+ mkdirSync(abs, { recursive: true });
+ applied.push({ ...remediation, applied: true });
+ }
+ }
+
+ const indexPath = resolveIndexPath(vault, null);
+ const indexKind = pathKind(indexPath);
+ if (indexKind === "file") {
+ checks.push({
+ name: "search-index",
+ status: "ok",
+ message: "search index exists",
+ });
+ } else {
+ checks.push({
+ name: "search-index",
+ status: "warning",
+ message:
+ indexKind === "missing"
+ ? "search index is missing or not yet built"
+ : "search index path is not a file",
+ remediation: "run o2b search reindex",
+ });
+ remediationPlan.push({
+ action: "run-command",
+ command: "o2b search reindex",
+ safe: true,
+ });
+ }
+
+ const restore = buildRestoreState(opts.restoreRunId, opts.forceRestore === true);
+ if (restore.requested) {
+ checks.push({
+ name: "snapshot-restore",
+ status: restore.refused ? "critical" : "warning",
+ message: restore.refused
+ ? "snapshot restore refused without --force-restore"
+ : "snapshot restore is explicit and force-enabled; delegate to rollback command",
+ remediation: restore.command,
+ });
+ if (restore.command) {
+ remediationPlan.push({
+ action: "restore-snapshot",
+ command: restore.command,
+ safe: false,
+ });
+ }
+ }
+
+ const report = buildProbeReport(checks);
+ const backoff = buildBackoff(opts.attempt ?? 0);
+ const auditRecord: AuditRecord = {
+ timestamp: now.toISOString(),
+ actor: "watchdog",
+ action: "brain_watchdog",
+ target: "Brain",
+ ok: report.counts.critical === 0,
+ details: {
+ counts: report.counts,
+ remediate: opts.remediate === true,
+ dry_run: opts.dryRun === true,
+ applied: applied.length,
+ restore,
+ backoff,
+ },
+ };
+ const auditPath = appendWatchdogAudit(vault, dirs.log, auditRecord);
+
+ return {
+ report,
+ remediation_plan: Object.freeze(remediationPlan),
+ applied_remediations: Object.freeze(applied),
+ restore,
+ backoff,
+ audit_path: auditPath,
+ };
+}
+
+function buildRestoreState(runId: string | undefined, force: boolean): WatchdogRestoreState {
+ if (runId === undefined || runId.trim() === "") return { requested: false, refused: false };
+ const trimmed = runId.trim();
+ if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+ return {
+ requested: true,
+ refused: true,
+ run_id: trimmed,
+ reason:
+ "snapshot restore run id must contain only letters, numbers, dot, dash, and underscore",
+ };
+ }
+ if (!force) {
+ return {
+ requested: true,
+ refused: true,
+ run_id: trimmed,
+ reason:
+ "snapshot restore requires --force-restore and should normally be run through rollback",
+ };
+ }
+ return {
+ requested: true,
+ refused: false,
+ run_id: trimmed,
+ command: `o2b brain rollback ${trimmed} --yes --force-rollback`,
+ };
+}
+
+function pathKind(path: string): "file" | "directory" | "other" | "missing" {
+ try {
+ const stat = statSync(path);
+ if (stat.isFile()) return "file";
+ if (stat.isDirectory()) return "directory";
+ return "other";
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+ throw error;
+ }
+}
+
+function appendWatchdogAudit(vault: string, logDir: string, record: AuditRecord): string {
+ try {
+ return appendAuditRecord(join(logDir, "watchdog"), record);
+ } catch (error) {
+ return appendAuditRecord(join(vault, ".open-second-brain", "watchdog-audit"), {
+ ...record,
+ ok: false,
+ details: {
+ ...record.details,
+ audit_fallback_reason: (error as Error).message ?? String(error),
+ },
+ });
+ }
+}
+
+function buildBackoff(attempt: number): WatchdogBackoff {
+ const safeAttempt = Math.max(0, Math.floor(attempt));
+ const base = 1000;
+ const max = 60_000;
+ return {
+ attempt: safeAttempt,
+ base_delay_ms: base,
+ next_delay_ms: Math.min(max, base * 2 ** safeAttempt),
+ max_delay_ms: max,
+ };
+}
diff --git a/src/core/reliability/atomic.ts b/src/core/reliability/atomic.ts
new file mode 100644
index 00000000..e595a1e0
--- /dev/null
+++ b/src/core/reliability/atomic.ts
@@ -0,0 +1,77 @@
+import {
+ closeSync,
+ existsSync,
+ fsyncSync,
+ mkdirSync,
+ openSync,
+ renameSync,
+ unlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export interface AtomicWriteTextOptions {
+ readonly mode?: number;
+ readonly validate?: (candidate: string) => void;
+}
+
+export function atomicWriteText(
+ targetPath: string,
+ candidate: string,
+ opts: AtomicWriteTextOptions = {},
+): void {
+ opts.validate?.(candidate);
+
+ const parent = dirname(targetPath);
+ mkdirSync(parent, { recursive: true });
+ const tempPath = join(
+ parent,
+ `.${basename(targetPath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,
+ );
+
+ let fileDescriptor: number | null = null;
+ try {
+ fileDescriptor = openSync(tempPath, "wx", opts.mode ?? 0o600);
+ writeFileSync(fileDescriptor, candidate, "utf8");
+ fsyncSync(fileDescriptor);
+ closeSync(fileDescriptor);
+ fileDescriptor = null;
+ renameSync(tempPath, targetPath);
+ fsyncDirectoryBestEffort(parent);
+ } catch (error) {
+ if (fileDescriptor !== null) {
+ try {
+ closeSync(fileDescriptor);
+ } catch {
+ // Best-effort cleanup; preserve the original write error.
+ }
+ }
+ if (existsSync(tempPath)) {
+ try {
+ unlinkSync(tempPath);
+ } catch {
+ // Best-effort cleanup; preserve the original write error.
+ }
+ }
+ throw error;
+ }
+}
+
+function fsyncDirectoryBestEffort(path: string): void {
+ let directoryDescriptor: number | null = null;
+ try {
+ directoryDescriptor = openSync(path, "r");
+ fsyncSync(directoryDescriptor);
+ } catch {
+ // Some platforms/filesystems reject directory fsync. The file fsync
+ // and atomic rename have already happened, so degrade quietly.
+ } finally {
+ if (directoryDescriptor !== null) {
+ try {
+ closeSync(directoryDescriptor);
+ } catch {
+ // Ignore close failures on a best-effort durability flush.
+ }
+ }
+ }
+}
diff --git a/src/core/reliability/audit.ts b/src/core/reliability/audit.ts
new file mode 100644
index 00000000..bc235c62
--- /dev/null
+++ b/src/core/reliability/audit.ts
@@ -0,0 +1,44 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { redactRawOutput } from "../redactor.ts";
+
+export interface AuditRecord {
+ readonly timestamp: string;
+ readonly actor: string;
+ readonly action: string;
+ readonly target: string;
+ readonly ok: boolean;
+ readonly details?: Record<string, unknown>;
+}
+
+export function appendAuditRecord(auditRoot: string, record: AuditRecord): string {
+ const timestamp = new Date(record.timestamp);
+ if (!Number.isFinite(timestamp.getTime())) {
+ throw new Error(`invalid audit timestamp: ${record.timestamp}`);
+ }
+ mkdirSync(auditRoot, { recursive: true });
+ const path = join(auditRoot, `${isoWeekLabel(timestamp)}.jsonl`);
+ const line = redactRawOutput(JSON.stringify(record), {
+ maxInput: Number.POSITIVE_INFINITY,
+ });
+
+ const fileDescriptor = openSync(path, "a", 0o600);
+ try {
+ writeFileSync(fileDescriptor, line + "\n", "utf8");
+ fsyncSync(fileDescriptor);
+ } finally {
+ closeSync(fileDescriptor);
+ }
+ return path;
+}
+
+export function isoWeekLabel(input: Date): string {
+ const date = new Date(Date.UTC(input.getUTCFullYear(), input.getUTCMonth(), input.getUTCDate()));
+ const dayNumber = date.getUTCDay() || 7;
+ date.setUTCDate(date.getUTCDate() + 4 - dayNumber);
+ const year = date.getUTCFullYear();
+ const yearStart = new Date(Date.UTC(year, 0, 1));
+ const week = Math.ceil(((date.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7);
+ return `${year}-W${String(week).padStart(2, "0")}`;
+}
diff --git a/src/core/reliability/lock.ts b/src/core/reliability/lock.ts
new file mode 100644
index 00000000..9b096243
--- /dev/null
+++ b/src/core/reliability/lock.ts
@@ -0,0 +1,50 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+import lockfile from "proper-lockfile";
+
+export interface FileLockOptions {
+ readonly staleMs?: number;
+ readonly retries?: number;
+ readonly retryDelayMs?: number;
+}
+
+export class FileLockError extends Error {
+ readonly targetPath: string;
+
+ constructor(targetPath: string, message: string) {
+ super(`failed to lock ${targetPath}: ${message}`);
+ this.name = "FileLockError";
+ this.targetPath = targetPath;
+ }
+}
+
+export async function withFileLock<T>(
+ targetPath: string,
+ opts: FileLockOptions,
+ callback: () => Promise<T> | T,
+): Promise<T> {
+ mkdirSync(dirname(targetPath), { recursive: true });
+
+ let release: (() => Promise<void>) | null = null;
+ try {
+ release = await lockfile.lock(targetPath, {
+ stale: opts.staleMs ?? 30_000,
+ realpath: false,
+ retries: {
+ retries: opts.retries ?? 3,
+ factor: 1,
+ minTimeout: opts.retryDelayMs ?? 250,
+ maxTimeout: opts.retryDelayMs ?? 250,
+ },
+ });
+ } catch (error) {
+ throw new FileLockError(targetPath, (error as Error).message ?? String(error));
+ }
+
+ try {
+ return await callback();
+ } finally {
+ await release();
+ }
+}
diff --git a/src/core/reliability/probe.ts b/src/core/reliability/probe.ts
new file mode 100644
index 00000000..1f1a6ab2
--- /dev/null
+++ b/src/core/reliability/probe.ts
@@ -0,0 +1,32 @@
+export const PROBE_STATUSES = Object.freeze(["ok", "warning", "critical"] as const);
+
+export type ProbeStatus = (typeof PROBE_STATUSES)[number];
+
+export interface ProbeCheck {
+ readonly name: string;
+ readonly status: ProbeStatus;
+ readonly message: string;
+ readonly remediation?: string;
+}
+
+export interface ProbeReport {
+ readonly ok: boolean;
+ readonly counts: Record<ProbeStatus, number>;
+ readonly checks: ReadonlyArray<ProbeCheck>;
+}
+
+export function buildProbeReport(checks: ReadonlyArray<ProbeCheck>): ProbeReport {
+ const counts: Record<ProbeStatus, number> = {
+ ok: 0,
+ warning: 0,
+ critical: 0,
+ };
+ for (const check of checks) {
+ counts[check.status]++;
+ }
+ return Object.freeze({
+ ok: counts.critical === 0 && counts.warning === 0,
+ counts: Object.freeze(counts),
+ checks: Object.freeze([...checks]),
+ });
+}
diff --git a/src/core/search/cjk-tokenizer.ts b/src/core/search/cjk-tokenizer.ts
new file mode 100644
index 00000000..3109d87d
--- /dev/null
+++ b/src/core/search/cjk-tokenizer.ts
@@ -0,0 +1,165 @@
+const HAN_RE = /\p{Script=Han}/u;
+const HIRAGANA_RE = /\p{Script=Hiragana}/u;
+const KATAKANA_RE = /\p{Script=Katakana}/u;
+const HANGUL_RE = /\p{Script=Hangul}/u;
+const LATINISH_RE = /[\p{L}\p{N}_-]/u;
+
+let jiebaCut: ((text: string) => string[]) | null | undefined;
+let tinySegment: ((text: string) => string[]) | null | undefined;
+
+export function containsCjk(text: string): boolean {
+ for (const char of text) {
+ if (isCjk(char)) return true;
+ }
+ return false;
+}
+
+export function tokenizeCjkSearchText(text: string): string[] {
+ const primaryTokens: string[] = [];
+ const fallbackTokens: string[] = [];
+ let index = 0;
+ while (index < text.length) {
+ const char = charAt(text, index);
+ const kind = cjkKind(char);
+ if (kind !== null) {
+ const start = index;
+ index += char.length;
+ while (index < text.length) {
+ const next = charAt(text, index);
+ if (cjkKind(next) !== kind) break;
+ index += next.length;
+ }
+ const segmented = segmentCjkRun(text.slice(start, index), kind);
+ primaryTokens.push(...segmented.primary);
+ fallbackTokens.push(...segmented.fallback);
+ continue;
+ }
+
+ if (LATINISH_RE.test(char) && !isCjk(char)) {
+ const start = index;
+ index += char.length;
+ while (index < text.length) {
+ const next = charAt(text, index);
+ if (!LATINISH_RE.test(next) || isCjk(next)) break;
+ index += next.length;
+ }
+ const token = text.slice(start, index).trim();
+ if (token.length > 0) primaryTokens.push(token);
+ continue;
+ }
+
+ index += char.length;
+ }
+ return unique([...primaryTokens, ...fallbackTokens]);
+}
+
+export function expandTextForCjkFts(text: string): string {
+ if (!containsCjk(text)) return text;
+ const tokens = tokenizeCjkSearchText(text);
+ if (tokens.length === 0) return text;
+ return `${text}\n${tokens.join(" ")}`;
+}
+
+function segmentCjkRun(run: string, kind: CjkKind): CjkSegmentedRun {
+ if (kind === "han") {
+ const cut = loadJiebaCut();
+ if (cut) return withFallbackTokens(run, cut(run), 2);
+ }
+ if (kind === "kana") {
+ const segment = loadTinySegmenter();
+ if (segment) return withFallbackTokens(run, segment(run), 2);
+ }
+ const fallback = fallbackCjkTokens(run, kind === "hangul" ? 1 : 2);
+ return { primary: fallback.primary, fallback: fallback.fallback };
+}
+
+function withFallbackTokens(
+ run: string,
+ segmented: ReadonlyArray<string>,
+ ngramSize: number,
+): CjkSegmentedRun {
+ const clean = segmented.map((token) => token.trim()).filter((token) => token.length > 0);
+ const fallback = fallbackCjkTokens(run, ngramSize);
+ return {
+ primary: unique([...clean, ...fallback.primary]),
+ fallback: fallback.fallback,
+ };
+}
+
+function fallbackCjkTokens(run: string, ngramSize: number): CjkSegmentedRun {
+ const chars = Array.from(run).filter((char) => isCjk(char));
+ const primary: string[] = [];
+ if (ngramSize > 1 && chars.length >= ngramSize) {
+ for (let index = 0; index <= chars.length - ngramSize; index++) {
+ primary.push(chars.slice(index, index + ngramSize).join(""));
+ }
+ }
+ if (primary.length === 0) primary.push(...chars);
+ return { primary: unique(primary), fallback: unique(chars) };
+}
+
+function loadJiebaCut(): ((text: string) => string[]) | null {
+ if (jiebaCut !== undefined) return jiebaCut;
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const mod = require("@node-rs/jieba") as {
+ cut?: (text: string) => string[];
+ default?: { cut?: (text: string) => string[] };
+ };
+ jiebaCut = mod.cut ?? mod.default?.cut ?? null;
+ } catch {
+ jiebaCut = null;
+ }
+ return jiebaCut;
+}
+
+function loadTinySegmenter(): ((text: string) => string[]) | null {
+ if (tinySegment !== undefined) return tinySegment;
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const mod = require("tiny-segmenter") as {
+ new (): { segment(text: string): string[] };
+ default?: new () => { segment(text: string): string[] };
+ };
+ const Segmenter = mod.default ?? mod;
+ const segmenter = new Segmenter();
+ tinySegment = (text: string) => segmenter.segment(text);
+ } catch {
+ tinySegment = null;
+ }
+ return tinySegment;
+}
+
+type CjkKind = "han" | "kana" | "hangul";
+
+interface CjkSegmentedRun {
+ readonly primary: ReadonlyArray<string>;
+ readonly fallback: ReadonlyArray<string>;
+}
+
+function cjkKind(char: string): CjkKind | null {
+ if (HAN_RE.test(char)) return "han";
+ if (HIRAGANA_RE.test(char) || KATAKANA_RE.test(char)) return "kana";
+ if (HANGUL_RE.test(char)) return "hangul";
+ return null;
+}
+
+function isCjk(char: string): boolean {
+ return cjkKind(char) !== null;
+}
+
+function charAt(text: string, index: number): string {
+ const codePoint = text.codePointAt(index);
+ return codePoint === undefined ? "" : String.fromCodePoint(codePoint);
+}
+
+function unique(tokens: ReadonlyArray<string>): string[] {
+ const seen = new Set<string>();
+ const out: string[] = [];
+ for (const token of tokens) {
+ if (seen.has(token)) continue;
+ seen.add(token);
+ out.push(token);
+ }
+ return out;
+}
diff --git a/src/core/search/fts.ts b/src/core/search/fts.ts
index 099271fe..f2461bf8 100644
--- a/src/core/search/fts.ts
+++ b/src/core/search/fts.ts
@@ -11,18 +11,17 @@
*/
import type { KeywordHit, Store } from "./store.ts";
+import { containsCjk, tokenizeCjkSearchText } from "./cjk-tokenizer.ts";
function quoteToken(t: string): string {
return `"${t.replace(/"/g, '""')}"`;
}
export function buildFtsMatch(rawQuery: string): string {
- const tokens = rawQuery
- .split(/\s+/)
- .map((t) => t.trim())
- .filter((t) => t.length > 0);
- if (tokens.length === 0) return "";
- return tokens.map(quoteToken).join(" ");
+ const tokens = containsCjk(rawQuery) ? tokenizeCjkSearchText(rawQuery) : rawQuery.split(/\s+/);
+ const cleaned = tokens.map((t) => t.trim()).filter((t) => t.length > 0);
+ if (cleaned.length === 0) return "";
+ return cleaned.map(quoteToken).join(" ");
}
/**
diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.ts
index 9d2244ec..3ff8a583 100644
--- a/src/core/search/indexer.ts
+++ b/src/core/search/indexer.ts
@@ -26,6 +26,7 @@ import {
import { basename, dirname } from "node:path";
import { chunkMarkdown } from "./chunker.ts";
+import { expandTextForCjkFts } from "./cjk-tokenizer.ts";
import { makeProvider } from "./embeddings/provider.ts";
import { extractLinks } from "./links.ts";
import { extractFrontmatterRelations } from "../graph/frontmatter-relations.ts";
@@ -194,6 +195,7 @@ async function indexInto(
const chunkInputs: ChunkInput[] = chunkResult.chunks.map((c) => ({
chunkIndex: c.chunkIndex,
content: c.content,
+ ftsContent: expandTextForCjkFts(c.content),
contentHash: sha256(c.content),
startLine: c.startLine,
endLine: c.endLine,
diff --git a/src/core/search/schema.ts b/src/core/search/schema.ts
index 50ae1dc6..145c17db 100644
--- a/src/core/search/schema.ts
+++ b/src/core/search/schema.ts
@@ -16,7 +16,7 @@ import { SearchError } from "./types.ts";
* this raises `SCHEMA_MISMATCH` on open β€” the operator must reindex
* with a newer binary.
*/
-export const LATEST_SCHEMA_VERSION = 4;
+export const LATEST_SCHEMA_VERSION = 5;
const DDL_V1 = `
CREATE TABLE IF NOT EXISTS documents (
@@ -221,6 +221,50 @@ export const MIGRATIONS: ReadonlyArray<Migration> = Object.freeze([
`);
},
},
+ {
+ // v5 (CJK search) - keep display content untouched while indexing
+ // an expanded FTS shadow column. Existing rows default to their
+ // current content until a reindex computes CJK token expansions.
+ version: 5,
+ up(db) {
+ const cols = db.query<{ name: string }, []>("PRAGMA table_info(chunks)").all();
+ if (!cols.some((c) => c.name === "fts_content")) {
+ db.exec("ALTER TABLE chunks ADD COLUMN fts_content TEXT NOT NULL DEFAULT ''");
+ db.exec("UPDATE chunks SET fts_content = content WHERE fts_content = ''");
+ }
+ db.exec(`
+ DROP TRIGGER IF EXISTS chunks_ai;
+ DROP TRIGGER IF EXISTS chunks_ad;
+ DROP TRIGGER IF EXISTS chunks_au;
+ DROP TABLE IF EXISTS chunk_fts;
+
+ CREATE VIRTUAL TABLE chunk_fts USING fts5(
+ fts_content,
+ heading_path,
+ content='chunks',
+ content_rowid='id',
+ tokenize='unicode61 remove_diacritics 2'
+ );
+
+ CREATE TRIGGER chunks_ai AFTER INSERT ON chunks BEGIN
+ INSERT INTO chunk_fts(rowid, fts_content, heading_path)
+ VALUES (new.id, new.fts_content, new.heading_path);
+ END;
+ CREATE TRIGGER chunks_ad AFTER DELETE ON chunks BEGIN
+ INSERT INTO chunk_fts(chunk_fts, rowid, fts_content, heading_path)
+ VALUES('delete', old.id, old.fts_content, old.heading_path);
+ END;
+ CREATE TRIGGER chunks_au AFTER UPDATE ON chunks BEGIN
+ INSERT INTO chunk_fts(chunk_fts, rowid, fts_content, heading_path)
+ VALUES('delete', old.id, old.fts_content, old.heading_path);
+ INSERT INTO chunk_fts(rowid, fts_content, heading_path)
+ VALUES (new.id, new.fts_content, new.heading_path);
+ END;
+
+ INSERT INTO chunk_fts(chunk_fts) VALUES('rebuild');
+ `);
+ },
+ },
]);
/** Read the current schema version from `index_state`. Returns 0 if not yet recorded. */
diff --git a/src/core/search/store.ts b/src/core/search/store.ts
index 82ed2214..e8660389 100644
--- a/src/core/search/store.ts
+++ b/src/core/search/store.ts
@@ -58,6 +58,7 @@ export interface DocumentSummary {
export interface ChunkInput {
readonly chunkIndex: number;
readonly content: string;
+ readonly ftsContent?: string;
readonly contentHash: string;
readonly startLine: number;
readonly endLine: number;
@@ -417,16 +418,18 @@ export class Store {
// ── query cache (v0.20.0) ────────────────────────────────────────────────────
- queryCacheGet(
- key: string,
- ): { generation: string; payload: string; createdAt: number } | null {
+ queryCacheGet(key: string): { generation: string; payload: string; createdAt: number } | null {
const row = this.db
.query<{ generation: string; payload: string; created_at: number }, [string]>(
"SELECT generation, payload, created_at FROM query_cache WHERE cache_key = ?",
)
.get(key);
if (!row) return null;
- return { generation: row.generation, payload: row.payload, createdAt: row.created_at };
+ return {
+ generation: row.generation,
+ payload: row.payload,
+ createdAt: row.created_at,
+ };
}
queryCachePut(key: string, generation: string, payload: string, createdAtMs: number): void {
@@ -450,13 +453,25 @@ export class Store {
listDocuments(): Map<string, DocumentSummary> {
const rows = this.db
- .query<{ id: number; path: string; content_hash: string; mtime: number; size: number }, []>(
- "SELECT id, path, content_hash, mtime, size FROM documents",
- )
+ .query<
+ {
+ id: number;
+ path: string;
+ content_hash: string;
+ mtime: number;
+ size: number;
+ },
+ []
+ >("SELECT id, path, content_hash, mtime, size FROM documents")
.all();
const map = new Map<string, DocumentSummary>();
for (const r of rows) {
- map.set(r.path, { id: r.id, contentHash: r.content_hash, mtime: r.mtime, size: r.size });
+ map.set(r.path, {
+ id: r.id,
+ contentHash: r.content_hash,
+ mtime: r.mtime,
+ size: r.size,
+ });
}
return map;
}
@@ -566,10 +581,10 @@ export class Store {
this.db.run("DELETE FROM chunks WHERE document_id = ?", [documentId]);
const insert = this.db.prepare<
{ id: number },
- [number, number, string, string, number, number, number, string, string, string]
+ [number, number, string, string, string, number, number, number, string, string, string]
>(
- "INSERT INTO chunks(document_id, chunk_index, content, content_hash, start_line, end_line, token_count, heading_path, created_at, updated_at) " +
- "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id",
+ "INSERT INTO chunks(document_id, chunk_index, content, fts_content, content_hash, start_line, end_line, token_count, heading_path, created_at, updated_at) " +
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id",
);
const now = nowIso();
for (const c of chunks) {
@@ -577,6 +592,7 @@ export class Store {
documentId,
c.chunkIndex,
c.content,
+ c.ftsContent ?? c.content,
c.contentHash,
c.startLine,
c.endLine,
@@ -836,7 +852,14 @@ export class Store {
if (documentIds.length === 0) return out;
const placeholders = documentIds.map(() => "?").join(",");
const rows = this.db
- .query<{ source_document_id: number; relation: string; target_path: string | null }, number[]>(
+ .query<
+ {
+ source_document_id: number;
+ relation: string;
+ target_path: string | null;
+ },
+ number[]
+ >(
"SELECT source_document_id, relation, target_path FROM links " +
`WHERE source_document_id IN (${placeholders}) AND relation IS NOT NULL ` +
"ORDER BY id",
@@ -880,7 +903,11 @@ export class Store {
"ORDER BY bm25 ASC LIMIT ?",
)
.all(fts5Query, prefix, prefix, limit);
- return rows.map((r) => ({ chunkId: r.chunk_id, documentId: r.document_id, bm25: r.bm25 }));
+ return rows.map((r) => ({
+ chunkId: r.chunk_id,
+ documentId: r.document_id,
+ bm25: r.bm25,
+ }));
}
const rows = this.db
@@ -890,7 +917,11 @@ export class Store {
"WHERE chunk_fts MATCH ? ORDER BY bm25 ASC LIMIT ?",
)
.all(fts5Query, limit);
- return rows.map((r) => ({ chunkId: r.chunk_id, documentId: r.document_id, bm25: r.bm25 }));
+ return rows.map((r) => ({
+ chunkId: r.chunk_id,
+ documentId: r.document_id,
+ bm25: r.bm25,
+ }));
}
semanticTopK(
diff --git a/src/mcp/schema-tools.ts b/src/mcp/schema-tools.ts
new file mode 100644
index 00000000..47756781
--- /dev/null
+++ b/src/mcp/schema-tools.ts
@@ -0,0 +1,121 @@
+import {
+ applySchemaAdminMutations,
+ buildSchemaGraph,
+ buildSchemaLint,
+ buildSchemaStats,
+ coerceSchemaMutations,
+ explainSchemaToken,
+ getActiveSchemaPack,
+ listSchemaPacks,
+ reviewSchemaOrphans,
+} from "../core/brain/schema-admin.ts";
+import type { SchemaMutation } from "../core/brain/schema-mutate.ts";
+import { INVALID_PARAMS, MCPError } from "./protocol.ts";
+import { coerceStr } from "./coerce.ts";
+import type { ToolDefinition } from "./tools.ts";
+
+export const SCHEMA_TOOLS: ReadonlyArray<ToolDefinition> = [
+ {
+ name: "get_active_schema_pack",
+ description: "Return the active Brain schema pack from Brain/_brain.yaml. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => getActiveSchemaPack(ctx.vault),
+ },
+ {
+ name: "list_schema_packs",
+ description: "List available Brain schema packs. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => listSchemaPacks(ctx.vault),
+ },
+ {
+ name: "schema_stats",
+ description: "Return Brain schema declaration, usage, metadata, and finding counts. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => buildSchemaStats(ctx.vault),
+ },
+ {
+ name: "schema_lint",
+ description:
+ "Return schema lint findings for unknown tokens and unused declarations. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => buildSchemaLint(ctx.vault),
+ },
+ {
+ name: "schema_graph",
+ description:
+ "Return schema graph nodes and edges for types, aliases, prefixes, and routing. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => buildSchemaGraph(ctx.vault),
+ },
+ {
+ name: "schema_explain_type",
+ description:
+ "Explain one schema token across declarations, usage, aliases, prefixes, and routing. Read-only.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ token: { type: "string", description: "Schema token to explain." },
+ },
+ required: ["token"],
+ additionalProperties: false,
+ },
+ handler: (ctx, args) => explainSchemaToken(ctx.vault, coerceStr(args, "token")!),
+ },
+ {
+ name: "schema_review_orphans",
+ description: "Return declared schema tokens that are currently unused. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => reviewSchemaOrphans(ctx.vault),
+ },
+ {
+ name: "schema_apply_mutations",
+ description:
+ "Apply an atomic batch of schema mutations to Brain/_brain.yaml and write an audit record.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ mutations: {
+ type: "array",
+ description: "Array of schema mutation objects.",
+ items: { type: "object" },
+ },
+ actor: {
+ type: "string",
+ description: "Audit actor label. Defaults to mcp.",
+ },
+ reason: {
+ type: "string",
+ description: "Optional audit reason.",
+ },
+ },
+ required: ["mutations"],
+ additionalProperties: false,
+ },
+ handler: async (ctx, args) => {
+ let mutations: SchemaMutation[];
+ let actor: string;
+ let reason: string | undefined;
+ try {
+ mutations = coerceSchemaMutations(args["mutations"]);
+ actor = coerceStr(args, "actor", false, "mcp")!;
+ reason = coerceStr(args, "reason", false) ?? undefined;
+ } catch (err) {
+ throw new MCPError(INVALID_PARAMS, (err as Error).message);
+ }
+ return await applySchemaAdminMutations(ctx.vault, mutations, {
+ actor,
+ reason,
+ });
+ },
+ },
+ {
+ name: "reload_schema_pack",
+ description: "Reload and return the active Brain schema pack from disk. Read-only.",
+ inputSchema: emptySchema(),
+ handler: (ctx) => getActiveSchemaPack(ctx.vault),
+ },
+];
+
+function emptySchema(): Record<string, unknown> {
+ return { type: "object", properties: {}, additionalProperties: false };
+}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index a38ea692..5db5b843 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -12,6 +12,10 @@
* (`BRAIN_TOOLS`).
* - Brain Search (`brain_search`) β€” `./search-tools.ts`
* (`SEARCH_TOOLS`).
+ * - Brain schema administration (`schema_*`) β€” `./schema-tools.ts`
+ * (`SCHEMA_TOOLS`).
+ * - Brain watchdog recovery probes (`brain_watchdog`) β€”
+ * `./watchdog-tools.ts` (`WATCHDOG_TOOLS`).
* - Pay Memory tools (`payment_*`, `asset_capture`) β€”
* `./pay-memory-tools.ts` (`PAY_MEMORY_TOOLS`).
*
@@ -23,17 +27,13 @@ import { discoverConfig, redactMapping } from "../core/config.ts";
import { computeBrainStatus } from "../core/brain/status.ts";
import { doctor } from "../core/doctor.ts";
import { isDir } from "../core/fs-utils.ts";
-import {
- resolveVaultScope,
- walkVaultScope,
-} from "../core/vault-scope/index.ts";
+import { resolveVaultScope, walkVaultScope } from "../core/vault-scope/index.ts";
import { BRAIN_TOOLS } from "./brain-tools.ts";
import { SEARCH_TOOLS, buildSearchStatusBlock } from "./search-tools.ts";
+import { SCHEMA_TOOLS } from "./schema-tools.ts";
+import { WATCHDOG_TOOLS } from "./watchdog-tools.ts";
import { PAY_MEMORY_TOOLS } from "./pay-memory-tools.ts";
-import {
- normalizeAgentArgument,
- PLACEHOLDER_AGENT_VALUES,
-} from "../core/agent-identity.ts";
+import { normalizeAgentArgument, PLACEHOLDER_AGENT_VALUES } from "../core/agent-identity.ts";
import { vaultRelative } from "../core/path-safety.ts";
import { listVaultPages } from "../core/vault.ts";
import { INVALID_PARAMS, METHOD_NOT_FOUND, MCPError } from "./protocol.ts";
@@ -99,9 +99,7 @@ function vaultRelpath(target: string, vault: string): string {
// ── Tool implementations ────────────────────────────────────────────────────
-async function toolStatus(
- ctx: ServerContext,
-): Promise<Record<string, unknown>> {
+async function toolStatus(ctx: ServerContext): Promise<Record<string, unknown>> {
const discovery = discoverConfig(ctx.configPath ?? undefined);
const vaultExists = isDir(ctx.vault);
const configKeys = Object.keys(discovery.data).toSorted();
@@ -109,8 +107,7 @@ async function toolStatus(
// `present: false` with zero counts.
const brain = vaultExists ? computeBrainStatus(ctx.vault) : null;
const searchDisabled = discovery.data["search_enabled"] === "false";
- const search =
- vaultExists && !searchDisabled ? await buildSearchStatusBlock(ctx) : null;
+ const search = vaultExists && !searchDisabled ? await buildSearchStatusBlock(ctx) : null;
// v0.10.9 β€” `vault` block exposes the shared exclusion policy plus
// aggregate include/exclude counts. Per-path detail lives in the CLI
// (`o2b vault status`); MCP payloads stay small.
@@ -331,15 +328,13 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {
properties: {
pattern: {
type: "string",
- description:
- "Optional case-insensitive substring matched against page titles.",
+ description: "Optional case-insensitive substring matched against page titles.",
},
limit: {
type: "integer",
minimum: 1,
maximum: 500,
- description:
- "Maximum number of matched pages to return (default 50).",
+ description: "Maximum number of matched pages to return (default 50).",
},
},
additionalProperties: false,
@@ -360,8 +355,7 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {
properties: {
repo: {
type: "string",
- description:
- "Optional repository root to validate plugin manifests.",
+ description: "Optional repository root to validate plugin manifests.",
},
},
additionalProperties: false,
@@ -377,8 +371,7 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {
properties: {
artifact_id: {
type: "string",
- description:
- "The artifact_id returned in a preview-truncated tool result envelope.",
+ description: "The artifact_id returned in a preview-truncated tool result envelope.",
},
},
required: ["artifact_id"],
@@ -387,16 +380,15 @@ export function buildToolTable(scope: ToolScope = "full"): ToolDefinition[] {
outputSchema: ARTIFACT_GET_OUTPUT_SCHEMA,
handler: toolArtifactGet,
},
+ ...SCHEMA_TOOLS,
+ ...WATCHDOG_TOOLS,
...PAY_MEMORY_TOOLS,
];
if (scope === "full") return all;
return all.filter((t) => WRITER_TOOL_NAMES.has(t.name));
}
-export function findTool(
- tools: ReadonlyArray<ToolDefinition>,
- name: string,
-): ToolDefinition {
+export function findTool(tools: ReadonlyArray<ToolDefinition>, name: string): ToolDefinition {
const tool = tools.find((t) => t.name === name);
if (!tool) throw new MCPError(METHOD_NOT_FOUND, `unknown tool: ${name}`);
return tool;
diff --git a/src/mcp/watchdog-tools.ts b/src/mcp/watchdog-tools.ts
new file mode 100644
index 00000000..4f936f68
--- /dev/null
+++ b/src/mcp/watchdog-tools.ts
@@ -0,0 +1,45 @@
+import { runBrainWatchdog } from "../core/brain/watchdog.ts";
+import { coerceBool, coerceInt, coerceStr } from "./coerce.ts";
+import type { ToolDefinition } from "./tools.ts";
+
+export const WATCHDOG_TOOLS: ReadonlyArray<ToolDefinition> = [
+ {
+ name: "brain_watchdog",
+ description:
+ "Probe Brain health and return safe recovery recommendations. Read-only unless remediate=true, which only creates missing Brain directories.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ remediate: {
+ type: "boolean",
+ description: "Apply safe remediations such as missing directory creation.",
+ },
+ dry_run: {
+ type: "boolean",
+ description: "Preview remediation without applying it.",
+ },
+ restore: {
+ type: "string",
+ description: "Snapshot run id to check restore readiness for.",
+ },
+ force_restore: {
+ type: "boolean",
+ description: "Allow restore recommendation to be emitted.",
+ },
+ attempt: {
+ type: "integer",
+ description: "Retry attempt for exponential backoff metadata.",
+ },
+ },
+ additionalProperties: false,
+ },
+ handler: (ctx, args) =>
+ runBrainWatchdog(ctx.vault, {
+ remediate: coerceBool(args, "remediate"),
+ dryRun: coerceBool(args, "dry_run"),
+ restoreRunId: coerceStr(args, "restore", false) ?? undefined,
+ forceRestore: coerceBool(args, "force_restore"),
+ attempt: coerceInt(args, "attempt", 0, 0, 32),
+ }),
+ },
+];
diff --git a/tests/cli/brain-schema-cli.test.ts b/tests/cli/brain-schema-cli.test.ts
index ebf8cfe9..9bb38c56 100644
--- a/tests/cli/brain-schema-cli.test.ts
+++ b/tests/cli/brain-schema-cli.test.ts
@@ -3,10 +3,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import {
- writePreference,
- type WritePreferenceInput,
-} from "../../src/core/brain/preference.ts";
+import { writePreference, type WritePreferenceInput } from "../../src/core/brain/preference.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import {
BRAIN_CONFIDENCE,
@@ -22,13 +19,7 @@ let configPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-brain-schema-cli-"));
vault = join(tmp, "vault");
- for (const dir of [
- "preferences",
- "retired",
- "inbox",
- "inbox/processed",
- "log",
- ]) {
+ for (const dir of ["preferences", "retired", "inbox", "inbox/processed", "log"]) {
mkdirSync(join(vault, "Brain", dir), { recursive: true });
}
writeFileSync(
@@ -101,14 +92,8 @@ describe("o2b brain schema", () => {
usage: { signal_types: Array<{ token: string; count: number }> };
findings: Array<{ kind: string; token: string }>;
};
- expect(payload.vocabulary.preference_types).toEqual([
- "preference",
- "research",
- "decision",
- ]);
- expect(payload.usage.signal_types).toEqual([
- { token: "external", count: 1 },
- ]);
+ expect(payload.vocabulary.preference_types).toEqual(["preference", "research", "decision"]);
+ expect(payload.usage.signal_types).toEqual([{ token: "external", count: 1 }]);
expect(payload.findings).toContainEqual(
expect.objectContaining({ kind: "unknown-token", token: "external" }),
);
@@ -121,13 +106,79 @@ describe("o2b brain schema", () => {
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("brain schema");
- expect(r.stdout).toContain(
- "preference_types: preference, research, decision",
- );
+ expect(r.stdout).toContain("preference_types: preference, research, decision");
expect(r.stdout).toContain("signal_types usage: external x1");
expect(r.stdout).toContain("[unknown-token] signal_types external");
- expect(r.stdout).toContain(
- "[unused-declaration] preference_types decision",
- );
+ expect(r.stdout).toContain("[unused-declaration] preference_types decision");
+ });
+
+ test("management subcommands expose stats, lint, graph, explain, orphans, and sync", async () => {
+ seedSchemaVault();
+
+ const stats = await runCli(["brain", "schema", "stats", "--json"], {
+ env: env(),
+ });
+ expect(stats.returncode).toBe(0);
+ expect(JSON.parse(stats.stdout).declared.preference_types).toBe(2);
+
+ const lint = await runCli(["brain", "schema", "lint", "--json"], {
+ env: env(),
+ });
+ expect(lint.returncode).toBe(0);
+ expect(JSON.parse(lint.stdout).findings.length).toBeGreaterThan(0);
+
+ const graph = await runCli(["brain", "schema", "graph", "--json"], {
+ env: env(),
+ });
+ expect(graph.returncode).toBe(0);
+ expect(
+ JSON.parse(graph.stdout).nodes.some((node: { id: string }) => node.id === "research"),
+ ).toBe(true);
+
+ const explain = await runCli(["brain", "schema", "explain", "research", "--json"], {
+ env: env(),
+ });
+ expect(explain.returncode).toBe(0);
+ expect(JSON.parse(explain.stdout).token).toBe("research");
+
+ const orphans = await runCli(["brain", "schema", "orphans", "--json"], {
+ env: env(),
+ });
+ expect(orphans.returncode).toBe(0);
+ expect(JSON.parse(orphans.stdout).orphans.length).toBeGreaterThan(0);
+
+ const sync = await runCli(["brain", "schema", "sync", "--dry-run", "--json"], { env: env() });
+ expect(sync.returncode).toBe(0);
+ expect(JSON.parse(sync.stdout).dry_run).toBe(true);
+ });
+
+ test("apply subcommand mutates the schema pack", async () => {
+ const mutation = JSON.stringify({
+ op: "add_type",
+ category: "preference_types",
+ token: "strategy",
+ });
+
+ const before = await runCli(["brain", "schema", "--json"], { env: env() });
+ expect(JSON.parse(before.stdout).vocabulary.preference_types).not.toContain("strategy");
+
+ const applied = await runCli(["brain", "schema", "apply", "--mutation", mutation, "--json"], {
+ env: env(),
+ });
+
+ expect(applied.returncode).toBe(0);
+ expect(JSON.parse(applied.stdout).applied).toBe(1);
+
+ const report = await runCli(["brain", "schema", "--json"], { env: env() });
+ expect(JSON.parse(report.stdout).vocabulary.preference_types).toContain("strategy");
+ });
+
+ test("rejects unknown schema subcommands", async () => {
+ const result = await runCli(["brain", "schema", "reprot", "--json"], {
+ env: env(),
+ });
+
+ expect(result.returncode).toBe(1);
+ expect(result.stderr).toContain("unknown subcommand reprot");
});
});
diff --git a/tests/cli/brain-session-hook.test.ts b/tests/cli/brain-session-hook.test.ts
new file mode 100644
index 00000000..a78e6545
--- /dev/null
+++ b/tests/cli/brain-session-hook.test.ts
@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-session-hook-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ bootstrapBrain(vault);
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: tester\n`);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
+
+describe("o2b brain session-hook", () => {
+ test("captures stdin hook payload as JSON", async () => {
+ const payload = {
+ hook_event_name: "UserPromptSubmit",
+ session_id: "cli-session",
+ prompt: "@osb feedback negative topic=cli-hook principle=capture-cli-hook",
+ };
+
+ const result = await runCli(["brain", "session-hook", "--json"], {
+ env: env(),
+ stdin: JSON.stringify(payload),
+ });
+
+ expect(result.returncode).toBe(0);
+ const body = JSON.parse(result.stdout);
+ expect(body.event).toBe("UserPromptSubmit");
+ expect(body.signals_created).toBe(1);
+ expect(
+ readdirSync(join(vault, "Brain", "inbox")).filter((name) => name.endsWith(".md")),
+ ).toHaveLength(1);
+ });
+
+ test("dry-run reports marker capture without writing", async () => {
+ const result = await runCli(["brain", "session-hook", "--dry-run", "--json"], {
+ env: env(),
+ stdin: JSON.stringify({
+ hook_event_name: "UserPromptSubmit",
+ prompt: "@osb feedback positive topic=dry-run principle=no-write",
+ }),
+ });
+
+ expect(result.returncode).toBe(0);
+ expect(JSON.parse(result.stdout).signals_created).toBe(0);
+ expect(
+ readdirSync(join(vault, "Brain", "inbox")).filter((name) => name.endsWith(".md")),
+ ).toHaveLength(0);
+ });
+});
diff --git a/tests/cli/brain-watchdog.test.ts b/tests/cli/brain-watchdog.test.ts
new file mode 100644
index 00000000..79e2a4ec
--- /dev/null
+++ b/tests/cli/brain-watchdog.test.ts
@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-brain-watchdog-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ bootstrapBrain(vault);
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: tester\n`);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
+
+describe("o2b brain watchdog", () => {
+ test("prints JSON probe report and search-index recommendation", async () => {
+ const result = await runCli(["brain", "watchdog", "--json"], {
+ env: env(),
+ });
+
+ expect(result.returncode).toBe(0);
+ const body = JSON.parse(result.stdout);
+ expect(body.report.checks).toContainEqual(
+ expect.objectContaining({ name: "search-index", status: "warning" }),
+ );
+ expect(body.remediation_plan).toContainEqual(
+ expect.objectContaining({ command: "o2b search reindex" }),
+ );
+ });
+
+ test("--remediate applies safe directory repair", async () => {
+ rmSync(brainDirs(vault).inbox, { recursive: true, force: true });
+
+ const result = await runCli(["brain", "watchdog", "--remediate", "--json"], { env: env() });
+
+ expect(result.returncode).toBe(0);
+ expect(JSON.parse(result.stdout).applied_remediations).toContainEqual(
+ expect.objectContaining({ action: "create-dir", target: "Brain/inbox" }),
+ );
+ expect(existsSync(brainDirs(vault).inbox)).toBe(true);
+ });
+
+ test("snapshot restore request exits 2 without --force-restore", async () => {
+ const result = await runCli(["brain", "watchdog", "--restore", "run-1", "--json"], {
+ env: env(),
+ });
+
+ expect(result.returncode).toBe(2);
+ expect(JSON.parse(result.stdout).restore.refused).toBe(true);
+ });
+
+ test("rejects partially numeric --attempt values", async () => {
+ const result = await runCli(["brain", "watchdog", "--attempt", "1foo"], {
+ env: env(),
+ });
+
+ expect(result.returncode).toBe(1);
+ expect(result.stderr).toContain("--attempt must be a non-negative integer");
+ });
+});
diff --git a/tests/core/brain.policy.test.ts b/tests/core/brain.policy.test.ts
index 33a86aa4..b14fdc46 100644
--- a/tests/core/brain.policy.test.ts
+++ b/tests/core/brain.policy.test.ts
@@ -68,10 +68,7 @@ describe("DEFAULT_BRAIN_CONFIG", () => {
describe("validateBrainConfig β€” happy path", () => {
test("accepts the default config", () => {
- const config = validateBrainConfig(
- JSON.parse(JSON.stringify(DEFAULT_BRAIN_CONFIG)),
- "<test>",
- );
+ const config = validateBrainConfig(JSON.parse(JSON.stringify(DEFAULT_BRAIN_CONFIG)), "<test>");
expect(config.schema_version).toBe(1);
expect(config.snapshots.retention_count).toBe(10);
});
@@ -104,9 +101,7 @@ describe("validateBrainConfig β€” schema block", () => {
const cfg = validateBrainConfig({ schema_version: 1 }, "<test>");
expect(cfg.schema).toBeUndefined();
- expect(resolveSchemaVocabulary(cfg.schema).preference_types).toEqual([
- "preference",
- ]);
+ expect(resolveSchemaVocabulary(cfg.schema).preference_types).toEqual(["preference"]);
});
test("accepts inline array declarations and resolves them through schema vocabulary", () => {
@@ -126,11 +121,7 @@ describe("validateBrainConfig β€” schema block", () => {
expect(cfg.schema?.preference_types).toEqual(["research", "decision"]);
const vocab = resolveSchemaVocabulary(cfg.schema);
- expect(vocab.preference_types).toEqual([
- "preference",
- "research",
- "decision",
- ]);
+ expect(vocab.preference_types).toEqual(["preference", "research", "decision"]);
expect(vocab.signal_types).toEqual(["feedback", "observation"]);
expect(vocab.page_types).toEqual(["note", "paper", "researcher"]);
expect(vocab.log_event_kinds).toContain("milestone");
@@ -140,9 +131,7 @@ describe("validateBrainConfig β€” schema block", () => {
let thrown: unknown;
try {
validateBrainConfig(
- parseBrainYaml(
- "schema_version: 1\nschema:\n preference_types: [research, ../escape]\n",
- ),
+ parseBrainYaml("schema_version: 1\nschema:\n preference_types: [research, ../escape]\n"),
"<schema>",
);
} catch (err) {
@@ -168,6 +157,45 @@ describe("validateBrainConfig β€” schema block", () => {
"schema.routing_hints: unknown field ignored (forward-compat)",
);
});
+
+ test("accepts schema mutation metadata without warning", () => {
+ const result = validateBrainConfigDetailed(
+ parseBrainYaml(
+ [
+ "schema_version: 1",
+ "schema:",
+ " preference_types: [research]",
+ " aliases:",
+ " - research=study",
+ " prefixes:",
+ " - pref=research",
+ " link_types: [supports]",
+ " extractable: [research]",
+ " expert_routing:",
+ " - research=schema-author",
+ ].join("\n"),
+ ),
+ "<schema>",
+ );
+
+ expect(result.config.schema?.aliases).toEqual(["research=study"]);
+ expect(result.config.schema?.prefixes).toEqual(["pref=research"]);
+ expect(result.config.schema?.link_types).toEqual(["supports"]);
+ expect(result.config.schema?.extractable).toEqual(["research"]);
+ expect(result.config.schema?.expert_routing).toEqual(["research=schema-author"]);
+ expect(result.warnings.map((warning) => warning.message)).not.toContain(
+ "schema.aliases: unknown field ignored (forward-compat)",
+ );
+ });
+
+ test("rejects blank schema metadata entries after trimming", () => {
+ expect(() =>
+ validateBrainConfig(
+ parseBrainYaml("schema_version: 1\nschema:\n aliases:\n - ' '\n"),
+ "<schema>",
+ ),
+ ).toThrow("schema.aliases[0]");
+ });
});
describe("validateBrainConfig β€” primary_agent", () => {
@@ -177,10 +205,7 @@ describe("validateBrainConfig β€” primary_agent", () => {
});
test("explicit null is accepted", () => {
- const cfg = validateBrainConfig(
- { schema_version: 1, primary_agent: null },
- "<test>",
- );
+ const cfg = validateBrainConfig({ schema_version: 1, primary_agent: null }, "<test>");
expect(cfg.primary_agent).toBeNull();
});
@@ -204,17 +229,14 @@ describe("validateBrainConfig β€” primary_agent", () => {
test("whitespace-only string rejected", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, primary_agent: " " },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, primary_agent: " " }, "<test>"),
).toThrow(/primary_agent/);
});
test("non-string non-null rejected", () => {
- expect(() =>
- validateBrainConfig({ schema_version: 1, primary_agent: 42 }, "<test>"),
- ).toThrow(/primary_agent/);
+ expect(() => validateBrainConfig({ schema_version: 1, primary_agent: 42 }, "<test>")).toThrow(
+ /primary_agent/,
+ );
});
});
@@ -229,18 +251,10 @@ describe("formatPrimaryAgentYamlValue", () => {
});
test("rejects values that would need escaping in the tiny YAML parser", () => {
- expect(() => formatPrimaryAgentYamlValue("agent\nnext")).toThrow(
- /disallowed character/,
- );
- expect(() => formatPrimaryAgentYamlValue("agent\rnext")).toThrow(
- /disallowed character/,
- );
- expect(() => formatPrimaryAgentYamlValue("agent\\path")).toThrow(
- /disallowed character/,
- );
- expect(() => formatPrimaryAgentYamlValue('agent "quoted"')).toThrow(
- /disallowed character/,
- );
+ expect(() => formatPrimaryAgentYamlValue("agent\nnext")).toThrow(/disallowed character/);
+ expect(() => formatPrimaryAgentYamlValue("agent\rnext")).toThrow(/disallowed character/);
+ expect(() => formatPrimaryAgentYamlValue("agent\\path")).toThrow(/disallowed character/);
+ expect(() => formatPrimaryAgentYamlValue('agent "quoted"')).toThrow(/disallowed character/);
});
});
@@ -256,26 +270,17 @@ describe("validateBrainConfig β€” error cases", () => {
});
test("unsupported schema_version β†’ error", () => {
- expect(() => validateBrainConfig({ schema_version: 99 }, "<test>")).toThrow(
- /schema_version/,
- );
+ 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/);
+ 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>",
- );
+ validateBrainConfig({ schema_version: 1, dream: { candidate_threshold: -1 } }, "<test>");
throw new Error("should have thrown");
} catch (err) {
expect(err).toBeInstanceOf(BrainConfigError);
@@ -285,40 +290,25 @@ describe("validateBrainConfig β€” error cases", () => {
test("non-integer threshold β†’ error", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, dream: { candidate_threshold: 3.5 } },
- "<test>",
- ),
+ 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>",
- ),
+ validateBrainConfig({ schema_version: 1, dream: { candidate_threshold: 0 } }, "<test>"),
).toThrow(/positive integer/);
});
test("snapshots.retention_count must be positive integer", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, snapshots: { retention_count: 0 } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, snapshots: { retention_count: 0 } }, "<test>"),
).toThrow(/positive integer/);
expect(() =>
- validateBrainConfig(
- { schema_version: 1, snapshots: { retention_count: -5 } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, snapshots: { retention_count: -5 } }, "<test>"),
).toThrow(/positive integer/);
expect(() =>
- validateBrainConfig(
- { schema_version: 1, snapshots: { retention_count: 1.5 } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, snapshots: { retention_count: 1.5 } }, "<test>"),
).toThrow(/positive integer/);
});
@@ -329,9 +319,7 @@ describe("validateBrainConfig β€” error cases", () => {
});
test("non-object block β†’ error", () => {
- expect(() =>
- validateBrainConfig({ schema_version: 1, dream: 5 }, "<test>"),
- ).toThrow(/dream/);
+ expect(() => validateBrainConfig({ schema_version: 1, dream: 5 }, "<test>")).toThrow(/dream/);
});
test("confidence.low_max_applied = 0 is allowed (non-negative)", () => {
@@ -350,12 +338,8 @@ describe("validateBrainConfig β€” warnings (forward-compat)", () => {
"<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.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);
});
@@ -389,18 +373,11 @@ describe("validateBrainConfig β€” vault block (v0.10.9)", () => {
},
"<test>",
);
- expect(cfg.vault?.ignore_paths).toEqual([
- ".git",
- "node_modules",
- "Brain/.snapshots",
- ]);
+ expect(cfg.vault?.ignore_paths).toEqual([".git", "node_modules", "Brain/.snapshots"]);
});
test("vault.ignore_paths empty array honoured as explicit empty", () => {
- const cfg = validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: [] } },
- "<test>",
- );
+ const cfg = validateBrainConfig({ schema_version: 1, vault: { ignore_paths: [] } }, "<test>");
expect(cfg.vault?.ignore_paths).toEqual([]);
});
@@ -413,44 +390,30 @@ describe("validateBrainConfig β€” vault block (v0.10.9)", () => {
});
test("vault block not a map β†’ BrainConfigError naming the field", () => {
- expect(() =>
- validateBrainConfig({ schema_version: 1, vault: 5 }, "<test>"),
- ).toThrow(/vault/);
+ expect(() => validateBrainConfig({ schema_version: 1, vault: 5 }, "<test>")).toThrow(/vault/);
});
test("vault.ignore_paths not an array β†’ BrainConfigError", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: "not-a-list" } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: "not-a-list" } }, "<test>"),
).toThrow(/vault\.ignore_paths/);
});
test("non-string entry β†’ BrainConfigError naming the index", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: [".git", 42] } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: [".git", 42] } }, "<test>"),
).toThrow(/vault\.ignore_paths\[1\]/);
});
test("empty-string entry rejected", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: [" "] } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: [" "] } }, "<test>"),
).toThrow(/non-empty/);
});
test("entry with newline is rejected", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: ["bad\nentry"] } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: ["bad\nentry"] } }, "<test>"),
).toThrow(/vault\.ignore_paths\[0\]/);
});
@@ -463,9 +426,7 @@ describe("validateBrainConfig β€” vault block (v0.10.9)", () => {
"<test>",
);
expect(result.config.vault?.ignore_paths).toEqual([".git"]);
- expect(
- result.warnings.some((w) => w.message.includes("unknown_extra")),
- ).toBe(true);
+ expect(result.warnings.some((w) => w.message.includes("unknown_extra"))).toBe(true);
});
test("DEFAULT_BRAIN_CONFIG_YAML parses with the vault block populated", () => {
@@ -493,16 +454,10 @@ describe("validateBrainConfig β€” vault block (v0.10.9)", () => {
test("entry that normalises to empty (e.g. './' / '/') is rejected", () => {
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: ["./"] } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: ["./"] } }, "<test>"),
).toThrow(/vault\.ignore_paths\[0\].*empty/);
expect(() =>
- validateBrainConfig(
- { schema_version: 1, vault: { ignore_paths: ["///"] } },
- "<test>",
- ),
+ validateBrainConfig({ schema_version: 1, vault: { ignore_paths: ["///"] } }, "<test>"),
).toThrow(/vault\.ignore_paths\[0\].*empty/);
});
@@ -581,9 +536,10 @@ describe("parseBrainYaml", () => {
const parsed = parseBrainYaml(
`schema_version: 1\nvault:\n ignore_paths: [Drafts, "Drafts/cache"]\n`,
);
- expect((parsed["vault"] as { ignore_paths: unknown }).ignore_paths).toEqual(
- ["Drafts", "Drafts/cache"],
- );
+ expect((parsed["vault"] as { ignore_paths: unknown }).ignore_paths).toEqual([
+ "Drafts",
+ "Drafts/cache",
+ ]);
});
test("parses one-level indented blocks", () => {
@@ -605,14 +561,10 @@ describe("parseBrainYaml", () => {
});
test("rejects nested blocks deeper than one level", () => {
- expect(() => parseBrainYaml(`top:\n middle:\n leaf: 1\n`)).toThrow(
- /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/);
+ expect(() => parseBrainYaml(`schema_version: 1\nschema_version: 2\n`)).toThrow(/duplicate/);
});
});
diff --git a/tests/core/brain.types.test.ts b/tests/core/brain.types.test.ts
index be205577..53df43cc 100644
--- a/tests/core/brain.types.test.ts
+++ b/tests/core/brain.types.test.ts
@@ -83,6 +83,8 @@ describe("BRAIN_* const enums", () => {
"note",
// Brain lifecycle suite (v0.21.0) reconcile-phase open questions
"reconcile",
+ // Runtime lifecycle hooks (v0.26.0)
+ "session-lifecycle",
]);
const actual = new Set<string>(Object.values(BRAIN_LOG_EVENT_KIND));
expect(actual).toEqual(expected);
diff --git a/tests/core/brain/schema-mutate.test.ts b/tests/core/brain/schema-mutate.test.ts
new file mode 100644
index 00000000..4f41e252
--- /dev/null
+++ b/tests/core/brain/schema-mutate.test.ts
@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ applySchemaMutations,
+ type SchemaMutation,
+} from "../../../src/core/brain/schema-mutate.ts";
+import { loadSchemaPack } from "../../../src/core/brain/schema-pack.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-schema-mutate-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ writeFileSync(
+ join(vault, "Brain", "_brain.yaml"),
+ [
+ "schema_version: 1",
+ "primary_agent: tester",
+ "schema:",
+ " preference_types: [research]",
+ " signal_types: [observation]",
+ " page_types: [paper]",
+ " log_event_kinds: [milestone]",
+ ].join("\n") + "\n",
+ "utf8",
+ );
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("applySchemaMutations", () => {
+ test("applies all schema mutation primitives through one atomic batch", async () => {
+ const mutations: SchemaMutation[] = [
+ { op: "add_type", category: "preference_types", token: "decision" },
+ {
+ op: "update_type",
+ category: "preference_types",
+ token: "research",
+ new_token: "research-note",
+ },
+ { op: "add_alias", token: "decision", alias: "choice" },
+ { op: "remove_alias", token: "decision", alias: "choice" },
+ { op: "add_prefix", prefix: "pref", token: "decision" },
+ { op: "remove_prefix", prefix: "pref" },
+ { op: "add_link_type", token: "supports" },
+ { op: "remove_link_type", token: "supports" },
+ { op: "set_extractable", token: "decision", enabled: true },
+ { op: "set_extractable", token: "decision", enabled: false },
+ { op: "set_expert_routing", token: "decision", expert: "schema-author" },
+ { op: "set_expert_routing", token: "decision", expert: null },
+ { op: "remove_type", category: "preference_types", token: "decision" },
+ ];
+
+ const result = await applySchemaMutations(vault, mutations, {
+ actor: "tester",
+ now: new Date("2026-05-30T12:00:00.000Z"),
+ });
+
+ expect(result.applied).toBe(13);
+ const pack = loadSchemaPack(vault);
+ expect(pack.declarations.preference_types).toEqual(["research-note"]);
+ expect(pack.aliases).toEqual({});
+ expect(pack.prefixes).toEqual({});
+ expect(pack.link_types).toEqual([]);
+ expect(pack.extractable).toEqual([]);
+ expect(pack.expert_routing).toEqual({});
+ expect(result.audit_path.endsWith("2026-W22.jsonl")).toBe(true);
+ });
+
+ test("rejects invalid batches before touching _brain.yaml", async () => {
+ const configPath = join(vault, "Brain", "_brain.yaml");
+ const before = readFileSync(configPath, "utf8");
+
+ await expect(
+ applySchemaMutations(
+ vault,
+ [{ op: "add_type", category: "preference_types", token: "123bad" }],
+ { actor: "tester" },
+ ),
+ ).rejects.toThrow("schema.preference_types");
+
+ expect(readFileSync(configPath, "utf8")).toBe(before);
+ });
+
+ test("rejects update_type when the source token is missing", async () => {
+ await expect(
+ applySchemaMutations(
+ vault,
+ [
+ {
+ op: "update_type",
+ category: "preference_types",
+ token: "missing",
+ new_token: "renamed",
+ },
+ ],
+ { actor: "tester" },
+ ),
+ ).rejects.toThrow("schema.preference_types: missing is not declared");
+ });
+
+ test("rejects multi-line expert routing values before rendering", async () => {
+ await expect(
+ applySchemaMutations(
+ vault,
+ [
+ {
+ op: "set_expert_routing",
+ token: "research",
+ expert: "schema-author\nother",
+ },
+ ],
+ { actor: "tester" },
+ ),
+ ).rejects.toThrow("expert must be a single line");
+ });
+
+ test("writes redacted mutation audit records", async () => {
+ const result = await applySchemaMutations(
+ vault,
+ [{ op: "add_type", category: "signal_types", token: "credential-note" }],
+ {
+ actor: "tester",
+ now: new Date("2026-05-30T12:00:00.000Z"),
+ reason: "api_key=secret-value",
+ },
+ );
+
+ const audit = readFileSync(result.audit_path, "utf8");
+ expect(audit).toContain("schema_apply_mutations");
+ expect(audit).toContain("***REDACTED***");
+ expect(audit).not.toContain("secret-value");
+ });
+});
diff --git a/tests/core/brain/session-lifecycle.test.ts b/tests/core/brain/session-lifecycle.test.ts
new file mode 100644
index 00000000..9dc9183b
--- /dev/null
+++ b/tests/core/brain/session-lifecycle.test.ts
@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { parseSignal } from "../../../src/core/brain/signal.ts";
+import { captureSessionLifecycleEvent } from "../../../src/core/brain/session-lifecycle.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-session-lifecycle-"));
+ bootstrapBrain(vault);
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("captureSessionLifecycleEvent", () => {
+ test("writes prompt markers immediately and dedupes repeats", async () => {
+ const payload = {
+ hook_event_name: "UserPromptSubmit",
+ session_id: "session-1",
+ prompt: '@osb feedback positive topic=lifecycle principle="capture prompt markers"',
+ };
+
+ const first = await captureSessionLifecycleEvent(vault, payload, {
+ agent: "tester",
+ now: new Date("2026-05-30T10:00:00Z"),
+ });
+ const second = await captureSessionLifecycleEvent(vault, payload, {
+ agent: "tester",
+ now: new Date("2026-05-30T10:00:01Z"),
+ });
+
+ expect(first.event).toBe("UserPromptSubmit");
+ expect(first.signals_created).toBe(1);
+ expect(first.signals_deduped).toBe(0);
+ expect(first.audit_path).toContain("session-lifecycle");
+ expect(first.log_path).toContain("Brain/log/2026-05-30.md");
+ expect(second.signals_created).toBe(0);
+ expect(second.signals_deduped).toBe(1);
+
+ const signalFiles = readdirSync(join(vault, "Brain", "inbox")).filter((name) =>
+ name.endsWith(".md"),
+ );
+ expect(signalFiles).toHaveLength(1);
+ const signal = parseSignal(join(vault, "Brain", "inbox", signalFiles[0]!));
+ expect(signal.topic).toBe("lifecycle");
+ expect(signal.source_type).toBe("session");
+ expect(signal.session_ref).toBe("session:session-1#UserPromptSubmit");
+ });
+
+ test("replays brain_feedback tool input through the same signal boundary", async () => {
+ const result = await captureSessionLifecycleEvent(
+ vault,
+ {
+ hook_event_name: "PostToolUse",
+ session_id: "session-2",
+ tool_name: "brain_feedback",
+ tool_input: {
+ topic: "tool-feedback",
+ signal: "negative",
+ principle: "capture feedback tool calls",
+ raw: "from hook payload",
+ },
+ },
+ { agent: "tester", now: new Date("2026-05-30T10:05:00Z") },
+ );
+
+ expect(result.signals_created).toBe(1);
+ expect(result.tool_replays).toBe(1);
+ });
+
+ test("records malformed payloads without throwing", async () => {
+ const result = await captureSessionLifecycleEvent(vault, null, {
+ agent: "tester",
+ now: new Date("2026-05-30T10:10:00Z"),
+ });
+
+ expect(result.event).toBe("unknown");
+ expect(result.malformed).toBe(1);
+ expect(result.signals_created).toBe(0);
+ expect(result.audit_path).toContain("session-lifecycle");
+ });
+
+ test.each(["SessionStart", "Stop", "SessionEnd"])(
+ "records %s as lifecycle-only observation",
+ async (event) => {
+ const result = await captureSessionLifecycleEvent(
+ vault,
+ { hook_event_name: event, session_id: "session-lifecycle-only" },
+ { agent: "tester", now: new Date("2026-05-30T10:15:00Z") },
+ );
+
+ expect(result.event).toBe(event);
+ expect(result.signals_created).toBe(0);
+ expect(result.signals_deduped).toBe(0);
+ expect(result.log_path).toContain("Brain/log/2026-05-30.md");
+ },
+ );
+});
diff --git a/tests/core/brain/watchdog.test.ts b/tests/core/brain/watchdog.test.ts
new file mode 100644
index 00000000..29580fb1
--- /dev/null
+++ b/tests/core/brain/watchdog.test.ts
@@ -0,0 +1,129 @@
+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 { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { runBrainWatchdog } from "../../../src/core/brain/watchdog.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-watchdog-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function seedHealthyVault(): void {
+ bootstrapBrain(vault);
+ const indexPath = join(vault, ".open-second-brain", "brain.sqlite");
+ mkdirSync(join(vault, ".open-second-brain"), { recursive: true });
+ writeFileSync(indexPath, "sqlite placeholder", "utf8");
+}
+
+describe("runBrainWatchdog", () => {
+ test("reports healthy probes with backoff and audit metadata", () => {
+ seedHealthyVault();
+
+ const result = runBrainWatchdog(vault, {
+ now: new Date("2026-05-30T12:00:00Z"),
+ attempt: 2,
+ });
+
+ expect(result.report.ok).toBe(true);
+ expect(result.report.counts.ok).toBeGreaterThanOrEqual(3);
+ expect(result.backoff.next_delay_ms).toBe(4000);
+ expect(result.audit_path).toContain("watchdog");
+ });
+
+ test("plans degraded probes without mutating by default", () => {
+ bootstrapBrain(vault);
+ rmSync(brainDirs(vault).inbox, { recursive: true, force: true });
+
+ const result = runBrainWatchdog(vault, {
+ now: new Date("2026-05-30T12:05:00Z"),
+ });
+
+ expect(result.report.ok).toBe(false);
+ expect(result.remediation_plan).toContainEqual(
+ expect.objectContaining({ action: "create-dir", target: "Brain/inbox" }),
+ );
+ expect(result.remediation_plan).toContainEqual(
+ expect.objectContaining({
+ action: "run-command",
+ command: "o2b search reindex",
+ }),
+ );
+ expect(existsSync(brainDirs(vault).inbox)).toBe(false);
+ });
+
+ test("reports wrong filesystem entry types as degraded", () => {
+ bootstrapBrain(vault);
+ rmSync(brainDirs(vault).log, { recursive: true, force: true });
+ writeFileSync(brainDirs(vault).log, "not a directory", "utf8");
+ const indexPath = join(vault, ".open-second-brain", "brain.sqlite");
+ mkdirSync(indexPath, { recursive: true });
+
+ const result = runBrainWatchdog(vault, {
+ now: new Date("2026-05-30T12:07:00Z"),
+ });
+
+ expect(result.report.ok).toBe(false);
+ expect(result.report.checks).toContainEqual(
+ expect.objectContaining({ name: "dir:Brain/log", status: "warning" }),
+ );
+ expect(result.report.checks).toContainEqual(
+ expect.objectContaining({ name: "search-index", status: "warning" }),
+ );
+ });
+
+ test("executes only safe remediations when explicitly requested", () => {
+ bootstrapBrain(vault);
+ rmSync(brainDirs(vault).processed, { recursive: true, force: true });
+
+ const result = runBrainWatchdog(vault, {
+ remediate: true,
+ now: new Date("2026-05-30T12:10:00Z"),
+ });
+
+ expect(result.applied_remediations).toContainEqual(
+ expect.objectContaining({
+ action: "create-dir",
+ target: "Brain/inbox/processed",
+ }),
+ );
+ expect(existsSync(brainDirs(vault).processed)).toBe(true);
+ });
+
+ test("refuses snapshot restore unless restore and force are explicit", () => {
+ bootstrapBrain(vault);
+
+ const refused = runBrainWatchdog(vault, {
+ restoreRunId: "run-1",
+ now: new Date("2026-05-30T12:15:00Z"),
+ });
+ expect(refused.restore.refused).toBe(true);
+ expect(refused.report.checks).toContainEqual(
+ expect.objectContaining({ name: "snapshot-restore", status: "critical" }),
+ );
+
+ const allowed = runBrainWatchdog(vault, {
+ restoreRunId: "run-1",
+ forceRestore: true,
+ now: new Date("2026-05-30T12:16:00Z"),
+ });
+ expect(allowed.restore.refused).toBe(false);
+ expect(allowed.restore.command).toBe("o2b brain rollback run-1 --yes --force-rollback");
+
+ const invalid = runBrainWatchdog(vault, {
+ restoreRunId: "run-1;rm",
+ forceRestore: true,
+ now: new Date("2026-05-30T12:17:00Z"),
+ });
+ expect(invalid.restore.refused).toBe(true);
+ expect(invalid.restore.command).toBeUndefined();
+ });
+});
diff --git a/tests/core/reliability.test.ts b/tests/core/reliability.test.ts
new file mode 100644
index 00000000..f300ab70
--- /dev/null
+++ b/tests/core/reliability.test.ts
@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import { appendAuditRecord } from "../../src/core/reliability/audit.ts";
+import { atomicWriteText } from "../../src/core/reliability/atomic.ts";
+import { withFileLock } from "../../src/core/reliability/lock.ts";
+import { buildProbeReport } from "../../src/core/reliability/probe.ts";
+
+let tmp: string;
+
+beforeEach(() => {
+ tmp = join(tmpdir(), `o2b-reliability-${crypto.randomUUID()}`);
+ mkdirSync(tmp, { recursive: true });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("atomicWriteText", () => {
+ test("preserves old content when validation rejects the candidate", () => {
+ const target = join(tmp, "state.yaml");
+ writeFileSync(target, "schema_version: 1\n", "utf8");
+
+ expect(() =>
+ atomicWriteText(target, "broken: true\n", {
+ validate: () => {
+ throw new Error("candidate failed lint");
+ },
+ }),
+ ).toThrow("candidate failed lint");
+
+ expect(readFileSync(target, "utf8")).toBe("schema_version: 1\n");
+ const leakedTemps = readdirSync(dirname(target)).filter(
+ (name) => name.startsWith(`.${basename(target)}.`) && name.endsWith(".tmp"),
+ );
+ expect(leakedTemps).toHaveLength(0);
+ });
+
+ test("writes the candidate atomically after validation passes", () => {
+ const target = join(tmp, "Brain", "_brain.yaml");
+
+ atomicWriteText(target, "schema_version: 1\nschema:\n", {
+ validate: (candidate) => expect(candidate).toContain("schema_version"),
+ });
+
+ expect(readFileSync(target, "utf8")).toBe("schema_version: 1\nschema:\n");
+ });
+});
+
+describe("withFileLock", () => {
+ test("serializes access to a lock target and releases after callback", async () => {
+ const target = join(tmp, "Brain", "_brain.yaml");
+ mkdirSync(join(tmp, "Brain"), { recursive: true });
+ writeFileSync(target, "schema_version: 1\n", "utf8");
+ const events: string[] = [];
+ let releaseFirst!: () => void;
+ let markFirstStarted!: () => void;
+ const firstCanRelease = new Promise<void>((resolve) => {
+ releaseFirst = resolve;
+ });
+ const firstStarted = new Promise<void>((resolve) => {
+ markFirstStarted = resolve;
+ });
+
+ const first = withFileLock(target, { staleMs: 1_000, retries: 0 }, async () => {
+ events.push("first");
+ markFirstStarted();
+ await firstCanRelease;
+ });
+ await firstStarted;
+
+ const second = withFileLock(
+ target,
+ { staleMs: 1_000, retries: 20, retryDelayMs: 10 },
+ async () => {
+ events.push("second");
+ },
+ );
+
+ await Promise.resolve();
+ expect(events).toEqual(["first"]);
+ releaseFirst();
+ await Promise.all([first, second]);
+
+ expect(events).toEqual(["first", "second"]);
+ });
+
+ test("does not create the target file while acquiring a lock", async () => {
+ const target = join(tmp, "Brain", "_brain.yaml");
+
+ await withFileLock(target, { staleMs: 1_000, retries: 0 }, () => {
+ expect(existsSync(target)).toBe(false);
+ });
+
+ expect(existsSync(target)).toBe(false);
+ });
+});
+
+describe("appendAuditRecord", () => {
+ test("appends redacted ISO-week JSONL audit records", () => {
+ const auditRoot = join(tmp, "Brain", "log", "schema-mutations");
+ const path = appendAuditRecord(auditRoot, {
+ timestamp: "2026-05-30T12:00:00.000Z",
+ actor: "tester",
+ action: "schema_apply_mutations",
+ target: "Brain/_brain.yaml",
+ ok: true,
+ details: { token: "research", api_key: "secret-value" },
+ });
+
+ expect(path.endsWith("2026-W22.jsonl")).toBe(true);
+ const lines = readFileSync(path, "utf8").trim().split("\n");
+ expect(lines).toHaveLength(1);
+ expect(lines[0]).toContain("schema_apply_mutations");
+ expect(lines[0]).toContain("***REDACTED***");
+ expect(lines[0]).not.toContain("secret-value");
+ });
+
+ test("rejects invalid timestamps before week bucketing", () => {
+ expect(() =>
+ appendAuditRecord(join(tmp, "Brain", "log", "schema-mutations"), {
+ timestamp: "not-a-date",
+ actor: "tester",
+ action: "schema_apply_mutations",
+ target: "Brain/_brain.yaml",
+ ok: true,
+ }),
+ ).toThrow("invalid audit timestamp");
+ });
+});
+
+describe("buildProbeReport", () => {
+ test("summarizes probe checks with stable severity counts", () => {
+ const report = buildProbeReport([
+ { name: "brain_root", status: "ok", message: "present" },
+ {
+ name: "search_index",
+ status: "warning",
+ message: "missing",
+ remediation: "run o2b search index",
+ },
+ {
+ name: "snapshot_restore",
+ status: "critical",
+ message: "drift detected",
+ },
+ ]);
+
+ expect(report.ok).toBe(false);
+ expect(report.counts).toEqual({ ok: 1, warning: 1, critical: 1 });
+ expect(report.checks.map((check) => check.name)).toEqual([
+ "brain_root",
+ "search_index",
+ "snapshot_restore",
+ ]);
+ });
+});
diff --git a/tests/core/search/cjk-tokenizer.test.ts b/tests/core/search/cjk-tokenizer.test.ts
new file mode 100644
index 00000000..a5bfc6ff
--- /dev/null
+++ b/tests/core/search/cjk-tokenizer.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ expandTextForCjkFts,
+ tokenizeCjkSearchText,
+} from "../../../src/core/search/cjk-tokenizer.ts";
+
+describe("tokenizeCjkSearchText", () => {
+ test("preserves mixed CJK and Latin token invariants", () => {
+ const tokens = tokenizeCjkSearchText("ζˆ‘ε–œζ¬’appleη”΅θ„‘");
+
+ expect(tokens).toContain("ε–œζ¬’");
+ expect(tokens).toContain("apple");
+ expect(tokens).toContain("η”΅θ„‘");
+ expect(tokens).toContain("η”΅");
+ expect(tokens.indexOf("apple")).toBeLessThan(tokens.indexOf("η”΅θ„‘"));
+ });
+
+ test("returns whitespace tokens unchanged when no CJK text is present", () => {
+ expect(tokenizeCjkSearchText("quick brown fox")).toEqual(["quick", "brown", "fox"]);
+ });
+});
+
+describe("expandTextForCjkFts", () => {
+ test("keeps original text and adds CJK search tokens", () => {
+ const expanded = expandTextForCjkFts("ζˆ‘ε–œζ¬’θ‹Ήζžœζ΄Ύ");
+
+ expect(expanded).toContain("ζˆ‘ε–œζ¬’θ‹Ήζžœζ΄Ύ");
+ expect(expanded).toContain("θ‹Ήζžœ");
+ expect(expanded).toContain("果派");
+ });
+});
diff --git a/tests/core/search/schema-migration-v4.test.ts b/tests/core/search/schema-migration-v4.test.ts
index 11053387..33d427fa 100644
--- a/tests/core/search/schema-migration-v4.test.ts
+++ b/tests/core/search/schema-migration-v4.test.ts
@@ -1,8 +1,8 @@
/**
- * Schema migration v3 -> v4 (query cache). v4 adds a `query_cache` table
- * backing the persistent, corpus-generation-gated query result cache. A
- * fresh index lands at v4; an existing v3 index upgrades without losing
- * any prior data.
+ * Schema migration v3 -> latest, with v4 query-cache coverage. v4 adds a
+ * `query_cache` table backing the persistent, corpus-generation-gated query
+ * result cache. Later migrations may run after it; this test keeps locking
+ * that a v3 index upgrades without losing any prior data.
*/
import { test, expect, beforeEach, afterEach } from "bun:test";
@@ -38,24 +38,31 @@ function hasTable(db: Database, name: string): boolean {
);
}
-test("fresh migration reaches v4 and creates query_cache", () => {
+function hasColumn(db: Database, table: string, name: string): boolean {
+ return db
+ .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+ .all()
+ .some((c) => c.name === name);
+}
+
+test("fresh migration reaches latest and creates query_cache", () => {
const db = new Database(dbPath);
- expect(applyMigrations(db)).toBe(4);
- expect(LATEST_SCHEMA_VERSION).toBe(4);
+ expect(applyMigrations(db)).toBe(LATEST_SCHEMA_VERSION);
expect(hasTable(db, "query_cache")).toBe(true);
+ expect(hasColumn(db, "chunks", "fts_content")).toBe(true);
db.close();
});
-test("applyMigrations is idempotent at v4", () => {
+test("applyMigrations is idempotent at latest", () => {
const db = new Database(dbPath);
- expect(applyMigrations(db)).toBe(4);
- expect(applyMigrations(db)).toBe(4);
+ expect(applyMigrations(db)).toBe(LATEST_SCHEMA_VERSION);
+ expect(applyMigrations(db)).toBe(LATEST_SCHEMA_VERSION);
db.close();
});
-test("a v3 index upgrades to v4 preserving prior data", () => {
+test("a v3 index upgrades to latest preserving prior data", () => {
const db = new Database(dbPath);
- applyMigrations(db); // -> v4
+ applyMigrations(db); // -> latest
db.run(
"INSERT INTO documents(id, path, title, content_hash, mtime, size, created_at, updated_at, indexed_at) " +
"VALUES (1, 'a.md', 'A', 'h', 1, 1, 't', 't', 't')",
@@ -66,8 +73,9 @@ test("a v3 index upgrades to v4 preserving prior data", () => {
expect(readSchemaVersion(db)).toBe(3);
expect(hasTable(db, "query_cache")).toBe(false);
- expect(applyMigrations(db)).toBe(4);
+ expect(applyMigrations(db)).toBe(LATEST_SCHEMA_VERSION);
expect(hasTable(db, "query_cache")).toBe(true);
+ expect(hasColumn(db, "chunks", "fts_content")).toBe(true);
const row = db.query<{ c: number }, []>("SELECT count(*) AS c FROM documents").get();
expect(row?.c).toBe(1);
db.close();
diff --git a/tests/core/search/search.test.ts b/tests/core/search/search.test.ts
index ba9000e8..647fc4b2 100644
--- a/tests/core/search/search.test.ts
+++ b/tests/core/search/search.test.ts
@@ -159,6 +159,19 @@ test("search supports Cyrillic query against Cyrillic content", async () => {
expect(out.results[0]?.path).toBe("Notes/ru.md");
});
+test("search supports unspaced CJK query segments without polluting result content", async () => {
+ writeMd(vault, "Notes/cjk.md", "# CJK\n\nζˆ‘ε–œζ¬’θ‹Ήζžœζ΄ΎοΌŒδΉŸε–œζ¬’ζœΊε™¨ε­¦δΉ γ€‚");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const out = await search(cfg, { query: "θ‹Ήζžœ", limit: 5 });
+
+ expect(out.results.map((r) => r.path)).toContain("Notes/cjk.md");
+ const hit = out.results.find((r) => r.path === "Notes/cjk.md");
+ expect(hit?.content).toContain("ζˆ‘ε–œζ¬’θ‹Ήζžœζ΄Ύ");
+ expect(hit?.content).not.toContain("θ‹Ήζžœ 果派");
+});
+
test("path_prefix filter scopes results", async () => {
const cfg = await seedKeyword();
await indexVault(cfg);
diff --git a/tests/hooks/session-capture.test.ts b/tests/hooks/session-capture.test.ts
new file mode 100644
index 00000000..8d91514d
--- /dev/null
+++ b/tests/hooks/session-capture.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+
+const HOOK = resolve(
+ dirname(fileURLToPath(import.meta.url)),
+ "..",
+ "..",
+ "hooks",
+ "session-capture.ts",
+);
+
+let vault: string;
+let configHome: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-hook-session-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-hook-session-cfg-"));
+ bootstrapBrain(vault);
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+async function runHook(
+ payload: unknown,
+ env: Record<string, string> = {},
+): Promise<{ stdout: string; stderr: string; exit: number }> {
+ const proc = Bun.spawn(["bun", "run", HOOK], {
+ stdin: "pipe",
+ stdout: "pipe",
+ stderr: "pipe",
+ env: {
+ PATH: process.env["PATH"] ?? "",
+ HOME: configHome,
+ VAULT_DIR: vault,
+ ...env,
+ },
+ });
+ proc.stdin.write(JSON.stringify(payload));
+ await proc.stdin.end();
+ const [stdout, stderr] = await Promise.all([
+ new Response(proc.stdout).text(),
+ new Response(proc.stderr).text(),
+ ]);
+ const exit = await proc.exited;
+ return { stdout, stderr, exit };
+}
+
+describe("session-capture hook", () => {
+ test("captures UserPromptSubmit markers and stays silent to the runtime", async () => {
+ const result = await runHook({
+ hook_event_name: "UserPromptSubmit",
+ session_id: "hook-session",
+ prompt: "@osb feedback positive topic=hook principle=capture-hook-prompt",
+ });
+
+ expect(result.exit).toBe(0);
+ expect(result.stderr).toBe("");
+ expect(result.stdout).toBe("");
+ expect(
+ readdirSync(join(vault, "Brain", "inbox")).filter((name) => name.endsWith(".md")),
+ ).toHaveLength(1);
+ });
+
+ test("does not crash on malformed payload", async () => {
+ const result = await runHook(null);
+
+ expect(result.exit).toBe(0);
+ expect(result.stderr).toBe("");
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 88bd0785..4ffe02dd 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -19,12 +19,7 @@ const savedEnv: Record<string, string | undefined> = {};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-test-"));
- for (const k of [
- "VAULT_AGENT_NAME",
- "VAULT_TIMEZONE",
- "VAULT_DIR",
- "OPEN_SECOND_BRAIN_CONFIG",
- ]) {
+ for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
savedEnv[k] = process.env[k];
delete process.env[k];
}
@@ -168,9 +163,7 @@ describe("tool listing", () => {
id: 2,
method: "tools/list",
})) as any;
- const names = r.result.tools
- .map((tool: { name: string }) => tool.name)
- .toSorted();
+ const names = r.result.tools.map((tool: { name: string }) => tool.name).toSorted();
expect(names).toEqual(
[
// Runtime capability diagnostics (v0.23.0).
@@ -238,6 +231,17 @@ describe("tool listing", () => {
"payment_request_consume",
// Search (added in v0.10.0).
"brain_search",
+ // Schema admin + watchdog recovery probes.
+ "get_active_schema_pack",
+ "list_schema_packs",
+ "schema_stats",
+ "schema_lint",
+ "schema_graph",
+ "schema_explain_type",
+ "schema_review_orphans",
+ "schema_apply_mutations",
+ "reload_schema_pack",
+ "brain_watchdog",
].toSorted(),
);
// Explicit grep: legacy writable tools are no longer advertised.
@@ -298,9 +302,7 @@ describe("tool calls", () => {
expect(s.vault.ignore_source).toBeDefined();
expect(["_brain.yaml", "defaults"]).toContain(s.vault.ignore_source);
expect(Array.isArray(s.vault.rules)).toBe(true);
- expect(
- s.vault.rules.some((r: { raw: string }) => r.raw === ".obsidian"),
- ).toBe(true);
+ expect(s.vault.rules.some((r: { raw: string }) => r.raw === ".obsidian")).toBe(true);
expect(typeof s.vault.included.files).toBe("number");
expect(typeof s.vault.included.dirs).toBe("number");
expect(typeof s.vault.excluded.dirs).toBe("number");
@@ -361,9 +363,7 @@ describe("tool calls", () => {
const s = r.result.structuredContent;
expect(s.limit).toBe(5);
expect(s.total_pages).toBeGreaterThanOrEqual(1);
- expect(
- s.pages.some((p: { title: string }) => p.title.includes("Sandbox")),
- ).toBe(true);
+ expect(s.pages.some((p: { title: string }) => p.title.includes("Sandbox"))).toBe(true);
});
// `second_brain_capture` and `event_log_append` are no longer
@@ -430,9 +430,7 @@ describe("tool calls", () => {
const r = (await callTool(server, "bad_contract")) as any;
expect(r.result.isError).toBe(true);
expect(r.result.structuredContent).toBeUndefined();
- expect(r.result.content[0].text).toContain(
- "bad_contract output contract failed",
- );
+ expect(r.result.content[0].text).toContain("bad_contract output contract failed");
});
});
@@ -481,7 +479,8 @@ describe("stdio loop", () => {
// + brain_morning_brief (v0.21.0) = 44.
// + brain_sources + brain_switch_vault (v0.22.0) = 46.
// + second_brain_capabilities (v0.23.0) = 47.
- expect(list.result.tools.length).toBe(47);
+ // + 9 schema admin tools + brain_watchdog = 57.
+ expect(list.result.tools.length).toBe(57);
});
test("returns parse error for invalid JSON", async () => {
diff --git a/tests/mcp/schema-tools.test.ts b/tests/mcp/schema-tools.test.ts
new file mode 100644
index 00000000..22e80eac
--- /dev/null
+++ b/tests/mcp/schema-tools.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+import { INVALID_PARAMS } from "../../src/mcp/protocol.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-schema-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ 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 });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "schema-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 });
+}
+
+describe("schema MCP tools", () => {
+ test("registers the schema administration surface", async () => {
+ const server = makeServer();
+ await initialize(server);
+
+ const response = await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 50,
+ method: "tools/list",
+ });
+ const names = ((response as any).result.tools as ReadonlyArray<{ name: string }>).map(
+ (tool) => tool.name,
+ );
+
+ expect(names).toContain("get_active_schema_pack");
+ expect(names).toContain("list_schema_packs");
+ expect(names).toContain("schema_stats");
+ expect(names).toContain("schema_lint");
+ expect(names).toContain("schema_graph");
+ expect(names).toContain("schema_explain_type");
+ expect(names).toContain("schema_review_orphans");
+ expect(names).toContain("schema_apply_mutations");
+ expect(names).toContain("reload_schema_pack");
+ });
+
+ test("applies schema mutations through the MCP handler", async () => {
+ const server = makeServer();
+ await initialize(server);
+
+ const applied = await call(server, "schema_apply_mutations", {
+ mutations: [{ op: "add_type", category: "preference_types", token: "decision" }],
+ });
+ expect((applied as any).result.structuredContent.applied).toBe(1);
+
+ const pack = await call(server, "get_active_schema_pack");
+ expect((pack as any).result.structuredContent.pack.declarations.preference_types).toContain(
+ "decision",
+ );
+ });
+
+ test("schema graph namespaces link type node ids", async () => {
+ const server = makeServer();
+ await initialize(server);
+
+ await call(server, "schema_apply_mutations", {
+ mutations: [
+ { op: "add_type", category: "preference_types", token: "decision" },
+ { op: "add_link_type", token: "decision" },
+ ],
+ });
+ const graph = await call(server, "schema_graph");
+ const nodes = (graph as any).result.structuredContent.nodes as ReadonlyArray<{ id: string }>;
+
+ expect(nodes.map((node) => node.id)).toContain("decision");
+ expect(nodes.map((node) => node.id)).toContain("link:decision");
+ });
+
+ test("schema apply reports coercion failures as invalid params", async () => {
+ const server = makeServer();
+ await initialize(server);
+
+ const response = await call(server, "schema_apply_mutations", {
+ mutations: "not an array",
+ });
+
+ expect((response as any).error.code).toBe(INVALID_PARAMS);
+ expect((response as any).error.message).toContain("mutations must be an array");
+ });
+});
diff --git a/tests/mcp/watchdog-tools.test.ts b/tests/mcp/watchdog-tools.test.ts
new file mode 100644
index 00000000..851e526e
--- /dev/null
+++ b/tests/mcp/watchdog-tools.test.ts
@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-watchdog-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+ bootstrapBrain(vault);
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "watchdog-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 },
+ });
+}
+
+describe("watchdog MCP tool", () => {
+ test("registers and returns a probe report", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const list = await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 50,
+ method: "tools/list",
+ });
+ const names = ((list as any).result.tools as ReadonlyArray<{ name: string }>).map(
+ (tool) => tool.name,
+ );
+ expect(names).toContain("brain_watchdog");
+
+ const result = await call(server, "brain_watchdog");
+ expect((result as any).result.structuredContent.report.checks).toContainEqual(
+ expect.objectContaining({ name: "search-index", status: "warning" }),
+ );
+ });
+});