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: Knowledge Provenance Suite - ingest, research, NER, derived facts, owner-scope, standing-query (v1.7.0) (#96)
Sol Aitken8b679fe23641
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex b0694941..000c12b5 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.6.0",+ "version": "1.7.0","description": "Plugin-first second brain package for AI agents and humans.","author": {"name": "Open Second Brain contributors"diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex d47becbb..73378d78 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.6.0",+ "version": "1.7.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","skills": "./skills","hooks": "./hooks/hooks.json",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c6ecdd66..7b5e1e47 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,47 @@ 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).+## [1.7.0] - 2026-06-13++### Added++- **Knowledge Provenance Suite.** Six features share one theme: every piece of+ knowledge in the brain carries its origin (which source, which premises, which+ owner, whether stated or inferred), and the operator can steer what surfaces.+ All generation lives on the agent side of the MCP boundary - Open Second Brain+ is provider-agnostic and bundles no model. Every behavioural change is opt-in;+ a vault that enables nothing is byte-identical in results, ordering, and shape.+ - **Source-ingest pipeline (`brain_ingest_source`).** One text-bearing source+ (document / note / URL text) becomes entity and concept pages plus a+ per-source summary page that backlinks the source, lists the entities it+ introduced, and lists its connections to pre-existing material. Idempotent on+ the source path. No OCR or binary/media path.+ - **Parameterized research pipeline (`brain_research_report`).** N consulted+ sources plus an agent synthesis become one dated report page where each+ finding cites the source that flagged it. A finding with no source, or one+ citing an unconsulted source, is rejected - no uncited claims.+ - **Model-based entity intake (`brain_intake_entities`).** The agent extracts+ entities from note text (it owns the recognition; no ML model is bundled) and+ submits them; Open Second Brain validates the typed payload and commits it+ through one shared, idempotent intake into the entity registry. Opt-in and+ non-blocking: a plain note write never triggers it.+ - **Derived-fact synthesis (`brain_derive_fact`).** The agent reasons a+ second-order conclusion from existing premises; Open Second Brain validates+ each premise exists and commits an unconfirmed preference carrying a+ `deduced`/`inferred` provenance level and premise links. Opt-in behind the+ `derived_fact_synthesis` guardrail. Recall trust ordering+ (`provenance_trust_ordering` guardrail) ranks stated > deduced > inferred in+ the active digest.+ - **Owner-scoped canonical facts.** A preference may declare an `owner:` token;+ `brain_query` gains an `agent_scope` argument (gated by the+ `owner_scoped_facts` guardrail) that returns an owner-private fact only to its+ owner and keeps shared facts visible. Reuses the v1.6 owner-visibility model;+ fails closed.+ - **Operator-editable standing-query attention layer.** The attention-flows+ mechanism gains a `standing_query` action: an operator declares scope tokens+ in a flow doc and the matching confirmed preferences always surface into the+ assembled context. Structural selector, language-agnostic.+## [1.6.0] - 2026-06-13### Added@@ -5303,6 +5344,7 @@ 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.+[1.7.0]: https://github.com/itechmeat/open-second-brain/compare/v1.6.0...v1.7.0[1.6.0]: https://github.com/itechmeat/open-second-brain/compare/v1.5.0...v1.6.0[1.5.0]: https://github.com/itechmeat/open-second-brain/compare/v1.4.0...v1.5.0[1.4.0]: https://github.com/itechmeat/open-second-brain/compare/v1.3.1...v1.4.0diff --git a/README.md b/README.mdindex 5a28e908..ec408437 100644--- a/README.md+++ b/README.md@@ -86,6 +86,7 @@ Each non-Hermes target writes a sidecar manifest under `<vault>/.open-second-bra- **Conversations survive compaction.** When the host compresses context and rotates the session id, capture and recall stitch the segments back into one conversation - any segment id returns the whole lineage.- **Memory that cleans itself, on your terms.** `o2b brain hygiene scan` surfaces contested facts, near-duplicate rules, stale derived pages, and never-recalled memories; `apply` executes only the findings you select, and stale pages recompile from their recorded sources with a dry-run preview.- **A vault that stays fresh, consistent, and scoped.** `o2b search watch` keeps the index live as you edit, debounced and incremental; note identity is Unicode-normalized so the same file is one entry across macOS and Linux devices instead of a phantom cross-device duplicate; and recall accepts an opt-in `agent_scope` so a page marked with an `owner:` is reachable only to its owner while shared pages stay open to all.+- **Knowledge that knows where it came from.** Drop a source document and the agent's extraction becomes cross-referenced entity and concept pages plus a summary page that backlinks the source and lists its connections; N sources become one dated report whose every finding cites the source that flagged it; a derived fact carries a `deduced`/`inferred` provenance level and links back to its premises, and recall trusts an operator-stated rule above a machine-derived one. A fact can declare an `owner:` so multi-agent brains keep separate truth spaces, and a standing-query attention flow surfaces the open loops you declare. The plugin never runs a model itself - the agent owns generation, the vault owns the durable, provenanced record - and every behaviour is opt-in.That is the day-to-day picture. The full capability surface, every CLI verb, and the mental model live in the [documentation](#documentation) below.diff --git a/docs/brainstorm/knowledge-provenance/cli-output/claude.md b/docs/brainstorm/knowledge-provenance/cli-output/claude.mdnew file mode 100644index 00000000..d2a19764--- /dev/null+++ b/docs/brainstorm/knowledge-provenance/cli-output/claude.md@@ -0,0 +1,36 @@+### Variant 1: Unified staged-intake kernel+- **Approach**: Generalize the existing `write-session` kernel into ONE provider-agnostic "intake transaction" that every generation-bearing feature (ingest, research-report, derived-facts, on-write NER) funnels through: the agent proposes a typed payload across an MCP/CLI boundary, OSB validates β provenance-stamps β cross-links β atomically commits. The boundary sits at this single kernel; primitive (a) is the discriminated `ExtractionIntake` payload (entities/concepts) shared by ingest and NER, (b) is a `Provenance` value object the kernel stamps at commit on any payload (source links, premise links, `stated|deduced|inferred` token), and (c) reuses `agent-scope.ts` for owner fields. Features 2/3/6 become payload variants or phases that call the same commit path.+- **Trade-offs**:+ - Pro: Maximum DRY β one validation/commit/provenance path, one place to guarantee byte-identical-when-off and atomicity.+ - Pro: Minimal new MCP tool surface; directly extends the cited kernel precedent.+ - Pro: Provenance and idempotency (sha256 dedup) live in exactly one tested seam.+ - Con: A large upfront abstraction conflicts with "one feature at a time via TDD" β the kernel must be near-complete before any feature lands, so the first commits carry the most risk.+ - Con: Over-generalization risk: ingest (many pages) and a single derived fact stress the same payload type very differently, inviting leaky union types or `as` crutches the conventions forbid.+ - Con: Hardest to keep each feature's commit atomic and independently revertable.+- **Complexity**: large+- **Risk**: high++### Variant 2: Per-feature pipelines over three shared libraries+- **Approach**: Each feature is its own module/pipeline with its own MCP tool or CLI command and its own TDD unit (`ingest.ts`, `research.ts`, a `derive` phase in `dream.ts`, `ner.ts`, owner-scoped facts on `preference-txn.ts`, an extension to `attention-flows.ts`), but all import three shared library functions rather than duplicating logic: `extractIntake()` (primitive a, shared by ingest + NER), `stampProvenance()`/citation builder (primitive b, shared by ingest + research + derive), and the existing owner-visibility helpers (primitive c). The generation boundary sits at each feature's own tool β the agent supplies extracted entities / summaries / report findings / derived reasoning, and each pipeline sequences-validates-commits using the shared libs (mirroring `importSession`'s dedup-hash blueprint).+- **Trade-offs**:+ - Pro: Matches the repo's established decomposition (v1.2 domain modules) and the one-atomic-commit-per-feature TDD constraint exactly β each feature fails-first, passes, ships independently.+ - Pro: Risk is isolated per feature; a flawed ingest pipeline cannot regress derived-facts.+ - Pro: DRY is enforced structurally (three named exports) without a monolithic type; easiest to keep flags independently opt-in and byte-identical-off.+ - Con: Larger MCP/CLI surface (several new tools on top of 72); sequencing/commit boilerplate is repeated per pipeline even when the libs aren't.+ - Con: Discipline-dependent β nothing forces callers through the shared libs, so drift is possible without review vigilance.+- **Complexity**: medium+- **Risk**: low++### Variant 3: Read-time provenance/visibility resolver with thin write adapters+- **Approach**: Push provenance, trust-ordering, and owner-scoping entirely into a read-time derivation at `packContext`/recall time, governed by frontmatter tokens and wikilinks; writes stay "dumb." The generation features become thin agent-side adapters that only emit notes carrying the right frontmatter (`provenance:`, `owner:`, premise links, `Sources` section), while one `resolveProvenance()`/`resolveVisibility()` layer at the read chokepoint does all ordering and filtering. Primitive (a) is a minimal extraction-intake that just writes tagged pages (shared by ingest + NER), (b) is the frontmatter token convention plus the read-time resolver (shared by ingest/research/derive), (c) is `agent-scope.ts` invoked at read for both facts and search β unifying owner-scoped facts with v1.6 agent-scope in one place.+- **Trade-offs**:+ - Pro: Strongest byte-identical-when-off guarantee β storage is unchanged; behavior only appears when the resolver is flagged on at read.+ - Pro: Trust ordering (stated > deduced > inferred) and owner filtering live in one read seam, naturally extending the read-time-derive pattern and the standing-query attention layer (feature 6 is already a read-time injector).+ - Con: Ingest and research are inherently write-heavy multi-page cross-referencing operations that don't fit a pure read-time model β those features still need real write pipelines, so the resolver only covers 3/6 features and a hybrid is unavoidable.+ - Con: Recomputing provenance/visibility on every context assembly adds read-path cost and complicates caching against the O(1) graph side-index.+ - Con: Frontmatter-only provenance is brittle if a page is hand-edited in Obsidian, with no commit-time validation to catch it.+- **Complexity**: medium+- **Risk**: medium++### Recommended: Variant 2+**Rationale**: It is the only variant that fits the hard process constraints β one feature at a time via TDD, one atomic revertable commit per unit, all inside a single 50-70 file PR β because each pipeline lands independently while the three named shared exports satisfy the DRY mandate without a monolithic kernel. It mirrors the repo's own precedents (`importSession`, `write-session`, v1.2 domain decomposition) and keeps each opt-in flag and its byte-identical-off guarantee isolated, whereas Variant 1's upfront kernel front-loads risk against the TDD cadence and Variant 3 only cleanly covers the read-side half of the suite. Where Variant 2 needs the agent-supplies-generation boundary it simply borrows the staged-intake shape inside the `extractIntake` primitive, getting Variant 1's key benefit without its monolith.diff --git a/docs/brainstorm/knowledge-provenance/cli-output/prompt.md b/docs/brainstorm/knowledge-provenance/cli-output/prompt.mdnew file mode 100644index 00000000..0311fb52--- /dev/null+++ b/docs/brainstorm/knowledge-provenance/cli-output/prompt.md@@ -0,0 +1,75 @@+You are brainstorming architectural variants for the following work. Do not write code. Do not write a final design. Only produce variants and a recommendation.++# Task++Ship a cohesive "Knowledge Provenance Suite" for Open Second Brain (a Markdown/Obsidian-first agent memory system; TypeScript/Bun; an MCP server plus an `o2b` CLI over a vault of notes, preferences, signals, entities). The suite bundles SIX related features that share one theme: every piece of knowledge in the brain should know its origin (which source, which premises, which owner, and whether it was stated by the operator or inferred by a machine), and the operator should be able to steer what surfaces into context. The six features:++1. SOURCE-INGEST PIPELINE (core). Drop a source document (plain text / Markdown / HTML / a URL's text) into the brain. The system extracts candidate entities and concepts, creates/updates entity and concept pages, writes a per-source summary page with a "Sources" section that links back to the raw artifact, and stamps a "connections to existing notes" list at capture time. One ingest touches many pages and cross-references them. (No OCR, no binary/PDF-image, no audio β text-bearing sources only.)++2. PARAMETERIZED RESEARCH PIPELINE. Pull N sources, run a configurable synthesis step, and write a dated structured report into the vault as a first-class page, where each finding cites which source flagged it. The report becomes a recall input itself.++3. DERIVED-FACT SYNTHESIS WITH PREMISE PROVENANCE. During the brain's "dream" maintenance pass (or an equivalent on-demand step), produce NEW second-order facts ("because A and B, therefore C") where every derived fact links back to its premise preferences/signals and carries a provenance label: stated (operator-asserted) vs deduced vs inferred. Recall must trust stated rules above machine-inferred ones. The plumbing (premise links, the provenance label surviving a read round-trip, recall ordering by provenance, byte-identical output when the feature is off) must be deterministic and testable; the actual reasoning text is model-generated and is NOT asserted in tests.++4. OWNER-SCOPED CANONICAL FACTS. A fact/preference may declare an owner token. When several agents write to one brain, each owner gets its own truth space; ownerless facts are shared. A query may pass an owner scope; absent scope means no filtering (byte-identical to today). Reuse the existing v1.6 owner-visibility model.++5. MODEL-BASED ENTITY EXTRACTION ON WRITE (NER). Discover entities in free note text (not only from explicit wikilinks) and feed them into the entity registry. MUST be done WITHOUT bundling any ML model or new heavy dependency: extraction is performed by the model the calling agent already has. Must be opt-in and must not block every note save synchronously. The prompt/contract must be language-agnostic (no hardcoded entity-type word lists in any language).++6. OPERATOR-EDITABLE STANDING-QUERY ATTENTION LAYER. An operator-editable declarative document defines queries that always fire when context is assembled and inject matching items (open loops, recent learnings) into the assembled context. A declarative "attention flows" mechanism ALREADY EXISTS (`src/core/brain/attention-flows.ts`, files under `Brain/attention/flows/`, injected into the context pack); the feature should extend that mechanism, not build a parallel one.++# Project context++Open Second Brain. TypeScript + Bun runtime. SQLite (FTS5 + sqlite-vec) search index. MCP server (72 tools) + `o2b` CLI + Obsidian/Markdown vault. Just shipped v1.6.0 ("Vault Integrity & Trust Suite": untrusted-source containment, NFC path identity, file-watcher sync, O(1) graph side-index, agent-scope recall isolation). Target for this work: v1.7.0.++Recent commits (git log --oneline):+- 6e59a42 feat: Vault Integrity & Trust Suite (v1.6.0)+- e4df212 feat: Search & Recall Quality Suite - explainable scores, trust, threshold, reinforce, eval (v1.5.0)+- 0340560 feat: Continuity, Hygiene & Freshness Suite (v1.3.0)+- 8972f13 refactor: SOLID/DRY decomposition - domain modules, unified helpers, surface guards (v1.2.0)+- 6651228 refactor: language-agnostic fact extraction + README slim (v1.1.0)++THE SINGLE MOST IMPORTANT ARCHITECTURAL FACT: OSB is provider-agnostic by construction. The kernel NEVER calls an LLM. As the codebase states: "OSB never calls an LLM; the calling agent owns generation, OSB owns sequencing, validation, and the final atomic commit." There is no LLM client in the repo (only an embedding-provider HTTP client for search vectors). The existing `brain_write_session` kernel is the precedent for this boundary: the agent supplies generated content through an MCP tool, OSB sequences/validates/commits it atomically. Features 1, 2, 3, and 5 all involve model generation (entity extraction, summarization, derived reasoning) and therefore CANNOT call a model from inside OSB β they must place the generation on the agent side of an MCP/CLI boundary and keep only deterministic sequencing, validation, provenance-stamping, and atomic vault writes inside OSB.++Related files (verified insertion points):+- src/core/brain/dream.ts (the maintenance pass; phases close->reconcile->synthesize->heal->log; new "derive" phase would slot between synthesize and heal)+- src/core/brain/preference.ts, preference-txn.ts (WritePreferenceInput, writePreferenceTxn; where a provenance label + premise links + owner field attach)+- src/core/brain/types.ts (BrainPreference, BrainSignal, DreamRunSummary, BrainGuardrailConfig)+- src/core/brain/policy.ts (BRAIN_GUARDRAIL_DEFAULTS, resolveGuardrails, loadGuardrailsConfigSafe, the YAML known-keys validator β the exact opt-in-flag pattern to mirror for each new feature flag)+- src/core/graph/agent-scope.ts (pageOwner / normalizeAgentScope / isOwnerVisible β generic, reusable for the fact layer, shipped v1.6)+- src/core/brain/entities/registry.ts (upsertEntity, relateEntities β where extracted entities land)+- src/core/brain/link-graph/unlinked-mentions.ts (findUnlinkedMentions β term-driven, structural, on-demand only)+- src/core/brain/signal.ts, note.ts (writeSignal, appendBrainNote β vault write primitives)+- src/core/brain/sessions/import.ts (importSession β the canonical "ingest external thing -> brain records" blueprint, with dedup-hash idempotency)+- src/core/brain/attention-flows.ts (existing declarative standing-query mechanism to extend for feature 6)+- src/core/brain/context-pack.ts (packContext β context-assembly chokepoint)+- src/core/brain/write-session/ (the provider-agnostic agent-supplies-generation kernel precedent)++Conventions:+- Byte-identical-when-flags-off is a hard guarantee: a vault that enables no new feature must return identical results, ordering, and output shape. Every behavioural change is opt-in behind a guardrail flag in `_brain.yaml`, defaulting off/loose.+- Read-time-derive / never-store-derived-enrichment is a recurring pattern.+- Language-agnostic: no hardcoded natural-language word lists (greetings, stopwords, keywords, entity-type names) in any language. Use structural signals, explicit frontmatter fields, corpus frequency, or agent/LLM extraction.+- Provenance is represented with wikilinks and frontmatter tokens; sha256 content hashing is used for idempotency/dedup.+- SOLID / KISS / DRY. TDD: tests must fail first, then pass. Conventional commits, one atomic unit per commit.++Constraints:+- No new heavy/ML dependency may be bundled (this is a hard operator requirement). Generation is the agent's; OSB stays dependency-light.+- No misleading fallbacks: a feature that cannot run (e.g. no model available) must fail clean or no-op honestly, never fabricate.+- No `as` / `as unknown as T` TypeScript cast crutches; construct values with the correct type from the start.+- The suite must exploit three shared DRY primitives rather than duplicating them: (a) ONE entity/concept extraction-intake primitive shared by the ingest pipeline AND the on-write NER; (b) ONE provenance/citation primitive shared by ingest, research-report, and derived-facts; (c) the existing owner-visibility model shared by owner-scoped facts AND v1.6 search agent-scope.+- Keep the whole suite shippable as ONE pull request (roughly 50-70 files including tests), implemented one feature at a time via TDD on a single branch.++# Required output format++Produce exactly 3 distinct architectural variants. For each variant:++### Variant N: <short name>+- **Approach**: 2-3 sentences describing the variant, with explicit attention to WHERE the agent/OSB generation boundary sits and HOW the three shared DRY primitives are factored.+- **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/knowledge-provenance/design.md b/docs/brainstorm/knowledge-provenance/design.mdnew file mode 100644index 00000000..03f42ca9--- /dev/null+++ b/docs/brainstorm/knowledge-provenance/design.md@@ -0,0 +1,171 @@+# Knowledge Provenance Suite - every fact knows where it came from++**Status:** draft+**Author:** claude-dev-agent (via feature-release-playbook)+**Audience:** implementation+**Target version:** 1.7.0++## Problem statement++Open Second Brain remembers conversations (session ingest) but cannot absorb the+documents a knowledge worker actually accumulates, cannot derive second-order+facts with traceable premises, cannot keep one agent's facts from polluting+another's, and gives the operator no declarative steering over what surfaces into+context. Across all of these the same gap recurs: a piece of knowledge in the+brain does not carry its origin - which source produced it, which premises it was+derived from, who owns it, and whether a human stated it or a machine inferred it.++## Scope++Six opt-in features, one unifying theme (knowledge carries its provenance),+shipped as one PR for v1.7.0:++1. **Source-ingest pipeline** - a text/Markdown/HTML/URL-text source becomes+ entity + concept pages plus a per-source summary page that links back to the+ raw artifact and lists its connections to existing notes.+2. **Parameterized research pipeline** - N sources become one dated, cited report+ page in the vault, each finding citing the source that flagged it.+3. **Derived-fact synthesis with premise provenance** - a `derive` step surfaces+ derivation-eligible premise sets deterministically; an agent supplies the+ derived fact; OSB commits it with premise links and a `stated|deduced|inferred`+ provenance label; recall trusts stated above inferred.+4. **Owner-scoped canonical facts** - a preference/fact may declare an `owner:`+ token; recall scoped to an owner sees that owner's facts plus shared+ (ownerless) facts. Reuses the v1.6 owner-visibility model.+5. **Model-based entity extraction on write (NER)** - entities discovered in free+ text by the calling agent's model are intaked into the entity registry. No ML+ dependency is bundled; opt-in; non-blocking.+6. **Operator-editable standing-query attention layer** - the existing+ `attention-flows` mechanism gains an operator-defined standing-query action so+ declared open loops / learnings always surface into the assembled context.++## Out of scope++- OCR, image/PDF-raster, audio, and any binary-media ingestion (the heavy-+ dependency surface of upstream `t_77f9d89b`). Text-bearing sources only.+- Observer-scoped / theory-of-mind beliefs (`t_741a64b0`) - declined for OSB and+ documented on the board.+- Any in-OSB LLM client. Generation stays on the agent side of the MCP/CLI+ boundary; OSB never calls a model.+- A daily-brief variant (`t_e4ddbe7c`) - not in this cycle's scope.++## Chosen approach++**Variant 2 - per-feature pipelines over three shared libraries** (consultant-+recommended; see `variants.md`). Each feature is its own module with its own MCP+tool or CLI verb and its own TDD unit, landing as one atomic commit. All features+import three shared primitives instead of duplicating logic:++- **(a) Extraction-intake** - the single validated path that turns+ agent-extracted entities/concepts into registry records (idempotent by content+ hash). Shared by the ingest pipeline and on-write NER.+- **(b) Provenance / citation** - a value object plus renderer that stamps source+ links, premise links, and a `stated|deduced|inferred` level onto a page, and+ renders the canonical `Sources` / citations section. Shared by ingest, research+ reports, and derived-facts.+- **(c) Owner-visibility** - the existing `src/core/graph/agent-scope.ts`+ (`pageOwner` / `normalizeAgentScope` / `isOwnerVisible`), reused unchanged at+ the fact/preference layer.++**Hardening over the bare variant:** each shared primitive is the ONLY exported+way to perform its operation - there is no public alternative write path for+extraction-intake or provenance-stamping, so a feature either imports the shared+export or fails to compile. This makes DRY a module-boundary guarantee rather than+a review-discipline hope.++**Provider-agnostic boundary:** for the four generation-bearing features (ingest,+research, derived-facts, NER) the model generation lives on the agent side. OSB+owns sequencing, validation, provenance-stamping, idempotent dedup, and the atomic+vault write - mirroring the `write-session` and `importSession` precedents. This+is the testable half and the half the operator agreed to cover.++## Design decisions++- **Opt-in behind `_brain.yaml` guardrail flags**, mirroring the v1.6+ `untrusted_source_delimiting` plumbing (defaults-merge-resolve + safe loader ++ known-keys validator). Every behavioural change defaults off; a vault that+ enables nothing is byte-identical in results, ordering, and shape. New tools/+ verbs are inherently opt-in (new surface), but any change to an EXISTING output+ (the dream pass for derived-facts; recall ordering by provenance; fact filtering+ by owner) is flag-gated.+- **Derived-facts split deterministic vs generated.** The `derive` phase in+ `dream.ts` only does the deterministic part: identify premise sets eligible for+ derivation (e.g. confirmed, high-confidence preferences sharing a scope) and+ record them as candidates. The actual reasoning is supplied by an agent through+ a `brain_derive_fact` MCP tool; OSB validates the premises exist, stamps+ `provenance: inferred` + premise wikilinks, and commits. Tests cover candidate+ identification, provenance round-trip, and recall ordering - never the model's+ prose.+- **Provenance label is a first-class preference field.** `BrainPreference` gains+ `provenance?: "stated" | "inferred"` (and the finer `deduced` where a premise+ chain is purely logical). Absent label reads as `stated` for every pre-existing+ preference, so existing prefs are unchanged. Recall ordering treats stated >+ deduced > inferred only when the trust-ordering flag is on.+- **Owner field reuses the v1.6 model verbatim.** `pageOwner` already reads an+ `owner:` token from any frontmatter map, so a preference's owner is read with+ the same function as a page's. No second implementation. Fact filtering applies+ `isOwnerVisible(owner, requestedScope)` and is byte-identical when no scope is+ requested.+- **NER is non-blocking and opt-in.** Note save never synchronously calls a model.+ Entity extraction is a separate agent-driven tool call (or a batched pass during+ dream), so it cannot add latency or token cost to a plain write. The extraction+ contract is structural and language-agnostic: the agent returns typed+ entity/concept records; OSB validates shape, never matches natural-language word+ lists.+- **Standing queries extend `attention-flows`, not a parallel system.** A new+ `standing_query` action type is added to the existing flow recipe; an+ operator-authored flow doc under `Brain/attention/flows/` declares the queries.+ Nothing fires unless the operator adds the action, so the default is unchanged.+- **No `as` cast crutches.** Payload shapes are built with conditional spreads and+ narrowing validators that return the correct literal types (the repo's+ established pattern), per `pref-no-typescript-cast-crutches`.++## File changes++New (illustrative; final paths settle during TDD):+- `src/core/brain/provenance/` - provenance value object + citation renderer+ (primitive b) and its tests.+- `src/core/brain/intake/` - extraction-intake validate+commit (primitive a) and+ its tests.+- `src/core/brain/ingest/` - source-ingest pipeline (feature 1) + MCP tool + CLI+ verb.+- `src/core/brain/research/` - research-report pipeline (feature 2) + MCP tool ++ CLI verb.+- `src/core/brain/dream-derived.ts` - the `derive` phase (feature 3).+- `src/mcp/brain/derive-tools.ts` - `brain_derive_fact` tool (feature 3).+- `src/core/brain/entities/ner-intake.ts` - on-write NER intake (feature 5) + MCP+ tool.+- standing-query extension inside `src/core/brain/attention-flows.ts` (feature 6).++Modified:+- `src/core/brain/types.ts` - `provenance` + premise links on `BrainPreference`;+ `owner` on the preference record; new guardrail flag fields; `derived` fields on+ `DreamRunSummary`.+- `src/core/brain/preference.ts`, `preference-txn.ts` - write/parse the new+ provenance + owner fields; frontmatter emission.+- `src/core/brain/policy.ts` - new guardrail flags through+ `BRAIN_GUARDRAIL_DEFAULTS`, `resolveGuardrails`, the YAML validator known-keys.+- `src/core/brain/dream.ts`, `dream-phases.ts`, `dream-workrun.ts` - wire the+ `derive` phase between synthesize and heal, flag-gated.+- recall/search ordering site - provenance trust ordering + fact owner filtering,+ flag-gated.+- `src/mcp/...` + `src/cli/...` + `command-manifest.ts` - register new tools/verbs.+- `CHANGELOG.md`, `README.md`, `package.json` (1.7.0) + `bun run+ scripts/sync-version.ts`.++## Risks and open questions++- **Scope breadth.** Six features touch sensitive subsystems (dream pass,+ preference store, context-pack, entity registry). Mitigation: strict one-feature-+ per-commit TDD; byte-identical-when-off as a test for each behavioural unit;+ shared primitives built and tested first so features compose rather than+ reinvent.+- **Lowest-ROI unit is the research pipeline** (`t_bdb46ec9`). It is the first to+ trim if the diff grows beyond a clean single PR; it sits on primitive (b) so it+ adds little once ingest exists.+- **Derive-phase byte-identical guarantee.** The dream pass must emit identical+ output when the derived-fact flag is off (the phase must be a true no-op).+ Verified by a dream-summary equality test with the flag off.+- **Standing-query cost.** Operator-declared queries run at context assembly; they+ must respect the existing character/token budget and not bypass it. The+ extension reuses the attention-flow injection path, which is already budgeted.diff --git a/docs/brainstorm/knowledge-provenance/plan.md b/docs/brainstorm/knowledge-provenance/plan.mdnew file mode 100644index 00000000..7464275e--- /dev/null+++ b/docs/brainstorm/knowledge-provenance/plan.md@@ -0,0 +1,136 @@+# Knowledge Provenance Suite - implementation plan++Build order: shared primitives first (so features compose, not reinvent), then+features cheapest-to-riskiest, each its own atomic conventional commit on+`feat/knowledge-provenance`. TDD per unit: failing test first, then implement,+then refactor green. Format + lint before every commit. Byte-identical-when-off is+a test obligation for every behavioural unit.++The version bump to 1.7.0 (`package.json` + `bun run scripts/sync-version.ts`) and+the CHANGELOG/README updates ride inside this PR (Phase 5), per CLAUDE.md.++## Tasks++### Task 1: Provenance / citation primitive (shared lib b)+- **Files**: `src/core/brain/provenance/provenance.ts` (+ index), `types.ts`+ (Provenance value object + `ProvenanceLevel = "stated" | "deduced" | "inferred"`),+ `tests/core/brain/provenance/provenance.test.ts`.+- **Builds**: a pure value object carrying source links, premise links, and a+ level; a renderer for the canonical `## Sources` / citations section; a sha256+ idempotency helper over the source identity. No I/O.+- **Acceptance**: deterministic stamp + render; parse round-trip recovers the+ level and links; identical input renders byte-identically; rejects an unknown+ level without an `as` cast.+- **Depends on**: none.++### Task 2: Extraction-intake primitive (shared lib a)+- **Files**: `src/core/brain/intake/extract-intake.ts` (+ index, types),+ `tests/core/brain/intake/extract-intake.test.ts`. Consumes+ `entities/registry.ts` (`upsertEntity`, `relateEntities`).+- **Builds**: the single validated path that turns an agent-supplied typed+ `ExtractionIntake` (entities + concepts + relations) into registry records,+ idempotent by content hash, provenance-stamped via Task 1. The ONLY exported+ intake path.+- **Acceptance**: a valid intake upserts the expected entities/relations; a+ re-run with the same payload is a no-op (dedup); a malformed payload is rejected+ with a typed error (no fabrication, no partial write); entity records carry the+ source provenance.+- **Depends on**: Task 1.++### Task 3: Guardrail flags plumbing+- **Files**: `src/core/brain/types.ts` (`BrainGuardrailConfig` ++ `ResolvedBrainGuardrailConfig`), `src/core/brain/policy.ts`+ (`BRAIN_GUARDRAIL_DEFAULTS`, `resolveGuardrails`, validator known-keys), tests+ in `tests/core/brain/policy*` / guardrail-config tests.+- **Builds**: the new opt-in flags (e.g. `derived_fact_synthesis`,+ `provenance_trust_ordering`, `owner_scoped_facts`), each defaulting off/loose,+ following the exact v1.6 `untrusted_source_delimiting` pattern.+- **Acceptance**: each flag parses from `_brain.yaml`, resolves to its default+ when absent, rejects a non-boolean with a `BrainConfigError`, and is accepted by+ the known-keys validator; defaults keep existing behaviour.+- **Depends on**: none (parallel-safe with 1-2, sequenced for clean commits).++### Task 4: Model-based entity extraction on write / NER (feature 5)+- **Files**: `src/core/brain/entities/ner-intake.ts`,+ `src/mcp/brain/ner-tools.ts` (a `brain_extract_entities` tool), command-manifest+ wiring, `tests/core/brain/entities/ner-intake.test.ts`.+- **Builds**: an agent-driven, opt-in, non-blocking intake of entities discovered+ in free text - the tool accepts the agent's typed extraction and routes it+ through the Task 2 primitive. No model call inside OSB; no ML dependency; note+ save is untouched.+- **Acceptance**: the tool intakes agent-supplied entities into the registry via+ primitive (a); a plain note write triggers no extraction and no latency; the+ contract carries no natural-language word list; invalid input fails clean.+- **Depends on**: Task 2.++### Task 5: Source-ingest pipeline (feature 1)+- **Files**: `src/core/brain/ingest/ingest.ts`, `src/mcp/brain/ingest-tools.ts`,+ `src/cli/brain/verbs/ingest.ts`, command-manifest wiring,+ `tests/core/brain/ingest/ingest.test.ts`.+- **Builds**: a deterministic pipeline that, given an agent-supplied extraction of+ a text/Markdown/HTML/URL-text source, creates/updates entity + concept pages+ (via primitive a), writes a per-source summary page with a `Sources` section and+ a capture-time connections list (via primitive b), idempotent by source hash.+- **Acceptance**: one ingest creates the expected entity/concept pages + a summary+ page linking back to the source; re-ingesting the same source is a no-op; the+ summary lists connections to pre-existing notes; no raw binary path exists.+- **Depends on**: Tasks 1, 2.++### Task 6: Parameterized research pipeline (feature 2)+- **Files**: `src/core/brain/research/research.ts`,+ `src/mcp/brain/research-tools.ts`, `src/cli/brain/verbs/research.ts`,+ command-manifest wiring, `tests/core/brain/research/research.test.ts`.+- **Builds**: a pipeline that takes N agent-supplied source findings + a synthesis+ payload and writes one dated report page where each finding cites its source+ (via primitive b). Report becomes a first-class recall input.+- **Acceptance**: a report page is written with per-finding citations back to the+ flagging source; the page is a valid recall input; deterministic given the same+ payload. (Lowest-ROI unit - first to trim if the diff overruns.)+- **Depends on**: Task 1.++### Task 7: Owner-scoped canonical facts (feature 4)+- **Files**: `src/core/brain/preference.ts` / `preference-txn.ts` (`owner` field+ write/parse), the recall/fact-read site (apply `isOwnerVisible`), `types.ts`,+ `tests/core/brain/owner-scoped-facts.test.ts`.+- **Builds**: an optional `owner:` token on a preference, read with the existing+ `pageOwner`; fact recall filtered by `isOwnerVisible(owner, requestedScope)`,+ flag-gated.+- **Acceptance**: an ownerless fact is always visible; an owned fact is visible+ only to its owner's scope; absent scope (or flag off) returns byte-identical+ results to today; reuses `agent-scope.ts` with no second implementation.+- **Depends on**: Task 3.++### Task 8: Derived-fact synthesis with premise provenance (feature 3)+- **Files**: `src/core/brain/dream-derived.ts`, `dream.ts` / `dream-phases.ts` /+ `dream-workrun.ts` (wire the `derive` phase, flag-gated),+ `src/mcp/brain/derive-tools.ts` (`brain_derive_fact`), `preference.ts` /+ `types.ts` (`provenance` + premise links), recall ordering site (trust ordering,+ flag-gated), `tests/core/brain/dream-derived.test.ts` + recall-ordering test.+- **Builds**: deterministic candidate-premise-set identification in the `derive`+ phase; `brain_derive_fact` commits an agent-supplied derived fact with premise+ links + `provenance: inferred` via primitive (b); recall trusts stated > deduced+ > inferred when the ordering flag is on.+- **Acceptance**: candidate identification is deterministic and tested; a derived+ fact round-trips its provenance label and premise links; recall orders+ stated-above-inferred only with the flag on; with the derived-fact flag off the+ dream summary is byte-identical to today (phase is a true no-op). No test asserts+ model-generated prose.+- **Depends on**: Tasks 1, 3.++### Task 9: Operator-editable standing-query attention layer (feature 6)+- **Files**: `src/core/brain/attention-flows.ts` (new `standing_query` action),+ context-pack injection path (reuse existing), `tests/core/brain/attention-flows*`.+- **Builds**: a `standing_query` action in the existing flow recipe so an+ operator-authored flow doc declares queries that always fire and inject matching+ items into the assembled context, within the existing budget.+- **Acceptance**: a flow with a `standing_query` action injects matching items+ into the context pack; a vault with no such action is byte-identical to today;+ injected items respect the existing character/token budget.+- **Depends on**: none (uses existing attention-flow injection).++### Task 10: Docs + version (Phase 5, inside this PR)+- **Files**: `CHANGELOG.md` (1.7.0 entry + link-ref), `README.md` (What you get /+ Safety bullets), `package.json` (1.7.0) + `bun run scripts/sync-version.ts`.+- **Acceptance**: `bun run scripts/sync-version.ts --check` passes; CHANGELOG+ heading and `package.json` agree; README describes the new capability.+- **Depends on**: Tasks 1-9.diff --git a/docs/brainstorm/knowledge-provenance/variants.md b/docs/brainstorm/knowledge-provenance/variants.mdnew file mode 100644index 00000000..ddf2b258--- /dev/null+++ b/docs/brainstorm/knowledge-provenance/variants.md@@ -0,0 +1,98 @@+# Knowledge Provenance Suite - variant audit trail++Primary consultant: Claude Code (`claude -p`), exit 0, three parseable variants.+Fallback (Codex) not invoked - primary returned a clean, complete set.++The full consultant output is preserved verbatim in `cli-output/claude.md`. The+three variants and the consultant's recommendation are reproduced below, followed+by the orchestrator decision.++## Variant 1: Unified staged-intake kernel++- **Approach**: Generalize the existing `write-session` kernel into ONE+ provider-agnostic "intake transaction" that every generation-bearing feature+ (ingest, research-report, derived-facts, on-write NER) funnels through: the+ agent proposes a typed payload across an MCP/CLI boundary, OSB validates ->+ provenance-stamps -> cross-links -> atomically commits. Primitive (a) is the+ discriminated `ExtractionIntake` payload shared by ingest and NER, (b) is a+ `Provenance` value object stamped at commit, (c) reuses `agent-scope.ts` for+ owner fields. Features 2/3/6 become payload variants or phases of the same+ commit path.+- **Trade-offs**: Maximum DRY and one tested seam for provenance/atomicity, but+ a large upfront abstraction conflicts with one-feature-at-a-time TDD (first+ commits carry the most risk), over-generalization invites leaky union types or+ `as` crutches, and per-feature atomic revertability is hardest.+- **Complexity**: large+- **Risk**: high++## Variant 2: Per-feature pipelines over three shared libraries++- **Approach**: Each feature is its own module/pipeline with its own MCP tool or+ CLI command and its own TDD unit (`ingest.ts`, `research.ts`, a `derive` phase+ in `dream.ts`, `ner.ts`, owner-scoped facts on `preference-txn.ts`, an+ extension to `attention-flows.ts`), but all import three shared library+ functions rather than duplicating logic: `extractIntake()` (primitive a,+ shared by ingest + NER), `stampProvenance()`/citation builder (primitive b,+ shared by ingest + research + derive), and the existing owner-visibility+ helpers (primitive c). The generation boundary sits at each feature's own tool;+ each pipeline sequences-validates-commits using the shared libs (mirroring+ `importSession`'s dedup-hash blueprint).+- **Trade-offs**: Matches the repo's domain-module decomposition and the+ one-atomic-commit-per-feature TDD constraint exactly; risk is isolated per+ feature; DRY is enforced via three named exports without a monolith; flags stay+ independently opt-in. Cons: larger MCP/CLI surface, repeated sequencing+ boilerplate, and shared-lib usage is discipline-dependent (drift possible+ without review vigilance).+- **Complexity**: medium+- **Risk**: low++## Variant 3: Read-time provenance/visibility resolver with thin write adapters++- **Approach**: Push provenance, trust-ordering, and owner-scoping entirely into+ a read-time derivation at `packContext`/recall time, governed by frontmatter+ tokens and wikilinks; writes stay "dumb". Generation features become thin+ agent-side adapters that emit notes with the right frontmatter, while one+ `resolveProvenance()`/`resolveVisibility()` layer at the read chokepoint does+ all ordering and filtering.+- **Trade-offs**: Strongest byte-identical-when-off guarantee (storage+ unchanged); trust ordering and owner filtering in one read seam. Cons: ingest+ and research are inherently write-heavy multi-page operations that do not fit a+ pure read-time model, so the resolver only covers 3/6 features and a hybrid is+ unavoidable; recomputing on every assembly adds read-path cost and complicates+ caching against the O(1) graph side-index; frontmatter-only provenance is+ brittle under hand edits with no commit-time validation.+- **Complexity**: medium+- **Risk**: medium++## Consultant recommendation: Variant 2++The consultant recommended Variant 2 as the only variant that fits the hard+process constraints (one feature at a time via TDD, one atomic revertable commit+per unit, single 50-70 file PR), because each pipeline lands independently while+three named shared exports satisfy the DRY mandate without a monolithic kernel.+It mirrors the repo's own precedents (`importSession`, `write-session`, the v1.2+domain decomposition) and keeps each opt-in flag and its byte-identical-off+guarantee isolated. Variant 1 front-loads risk against the TDD cadence; Variant 3+cleanly covers only the read-side half of the suite.++## Orchestrator decision: accept Variant 2, with one hardening++Accepted. Variant 2 is the correct fit for this repo's TDD/atomic-commit cadence+and the single-PR constraint, and it is the only variant under which a flawed+ingest pipeline cannot regress derived-facts.++One hardening is added to close Variant 2's single weakness (shared-lib usage is+discipline-dependent): the three shared primitives are made the ONLY exported way+to perform their operation. There is no public alternative write path for+extraction-intake or provenance-stamping - features import the shared export or+they do not compile. This converts "drift is possible without review vigilance"+into a type-and-module-boundary guarantee, recovering Variant 1's single-seam+benefit without its monolith or its front-loaded risk.++A second clarification follows directly from the project's provider-agnostic+kernel (OSB never calls an LLM): for the four generation-bearing features+(ingest, research, derived-facts, NER), all model generation lives on the agent+side of an MCP/CLI boundary. OSB owns only the deterministic half - sequencing,+validation, provenance-stamping, idempotent dedup, and the atomic vault write -+which is exactly the half that is testable and the half the operator agreed to+cover with tests. No ML dependency is bundled anywhere in the suite.diff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex b5abee1b..bafad69f 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": "1.6.0",+ "version": "1.7.0","activation": { "onStartup": true },"skills": ["./skills"],"contracts": {diff --git a/package.json b/package.jsonindex 4aa2dd2f..8a342e48 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.6.0",+ "version": "1.7.0","private": false,"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.","keywords": [diff --git a/plugin.yaml b/plugin.yamlindex da1c995c..db9e616e 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.6.0"+version: "1.7.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 9fae1eae..34461995 100644--- a/plugins/codex/.codex-plugin/plugin.json+++ b/plugins/codex/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "1.6.0",+ "version": "1.7.0","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","author": {"name": "Open Second Brain contributors",diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex da1c995c..db9e616e 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "1.6.0"+version: "1.7.0"description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."author: "Open Second Brain contributors"memory_provider: truediff --git a/pyproject.toml b/pyproject.tomlindex d83d9417..79863cd7 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 = "1.6.0"+version = "1.7.0"description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."readme = "README.md"requires-python = ">=3.11"diff --git a/src/core/brain/active.ts b/src/core/brain/active.tsindex c3e18dc5..7f184288 100644--- a/src/core/brain/active.ts+++ b/src/core/brain/active.ts@@ -41,10 +41,12 @@ import {MOST_APPLIED_LIMIT_DEFAULT,MOST_APPLIED_WINDOW_DAYS_DEFAULT,loadBrainConfig,+ loadGuardrailsConfigSafe,} from "./policy.ts";import { parsePreference, parseRetired } from "./preference.ts";import { brainActivePath, brainDirs } from "./paths.ts";import { isoSecond } from "./time.ts";+import { sortByProvenanceTrust } from "./provenance/trust-order.ts";import { BRAIN_PREFERENCE_STATUS, type BrainPreference, type BrainRetired } from "./types.ts";const RECENTLY_RETIRED_COUNT = 3;@@ -99,9 +101,17 @@ export function regenerateActive(const preferences = readActivePreferences(vault);const retiredRecent = readRecentlyRetired(vault, RECENTLY_RETIRED_COUNT);- const confirmed = preferences+ // Confirmed prefs sort by confidence then id. When provenance trust+ // ordering is on, re-rank stated > deduced > inferred as the primary key+ // (stable, so the confidence order is preserved within a trust band). Off+ // by default -> byte-identical.+ const confirmedByConfidence = preferences.filter((p) => p.status === BRAIN_PREFERENCE_STATUS.confirmed).toSorted(sortByConfidenceThenId);+ const confirmed = sortByProvenanceTrust(+ confirmedByConfidence,+ loadGuardrailsConfigSafe(vault).provenance_trust_ordering,+ );const quarantine = preferences.filter((p) => p.status === BRAIN_PREFERENCE_STATUS.quarantine).toSorted(sortByIdAscending);diff --git a/src/core/brain/attention-flows.ts b/src/core/brain/attention-flows.tsindex af6ad6c8..73051cd7 100644--- a/src/core/brain/attention-flows.ts+++ b/src/core/brain/attention-flows.ts@@ -2,17 +2,30 @@ import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";import { join } from "node:path";import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";-import { attentionFlowsDir } from "./paths.ts";+import { attentionFlowsDir, brainDirs } from "./paths.ts";import { listProceduralMemory } from "./procedural-memory.ts";import { listPendingSkillProposals } from "./skill-proposals.ts";import { listRecurrenceEntries } from "./recurrence.ts";+import { parsePreference } from "./preference.ts";+import { BRAIN_PREFERENCE_STATUS } from "./types.ts";-export type AttentionFlowAction = "open_proposals" | "high_recurrence" | "active_procedures";+export type AttentionFlowAction =+ | "open_proposals"+ | "high_recurrence"+ | "active_procedures"+ | "standing_query";export interface AttentionFlowRecipe {readonly id: string;readonly title: string;readonly actions: ReadonlyArray<AttentionFlowAction>;+ /**+ * Operator-declared scope tokens for the `standing_query` action. A+ * confirmed preference whose `scope` is in this set always surfaces into+ * the assembled context. Structural selector - never a natural-language+ * phrase - so the attention layer stays language-agnostic.+ */+ readonly standingQueryScopes: ReadonlyArray<string>;readonly sourcePath: string;}@@ -73,6 +86,7 @@ export function listAttentionFlows(vault: string): ReadonlyArray<AttentionFlowReid: typeof fm["id"] === "string" ? fm["id"] : name.replace(/\.md$/, ""),title: typeof fm["title"] === "string" ? fm["title"] : name.replace(/\.md$/, ""),actions,+ standingQueryScopes: normalizeStandingQueryScopes(fm["standing_queries"]),sourcePath: path,});} catch {@@ -107,6 +121,11 @@ export function evaluateAttentionFlow(vault: string, flowId: string): AttentionF.filter((entry) => entry.kind === "procedure" || entry.kind === "skill").map((entry) => `${entry.title} [${entry.kind}]`);sections.push({ action, items: Object.freeze(items) });+ continue;+ }+ if (action === "standing_query") {+ const items = listConfirmedPreferencesByScope(vault, flow.standingQueryScopes);+ sections.push({ action, items: Object.freeze(items) });}}@@ -137,6 +156,7 @@ function normalizeActions(value: unknown): ReadonlyArray<AttentionFlowAction> {"open_proposals","high_recurrence","active_procedures",+ "standing_query",]);const out: AttentionFlowAction[] = [];if (Array.isArray(value)) {@@ -150,6 +170,50 @@ function normalizeActions(value: unknown): ReadonlyArray<AttentionFlowAction> {return Object.freeze([...new Set(out)]);}+/** Parse the operator-declared `standing_queries` scope tokens. */+function normalizeStandingQueryScopes(value: unknown): ReadonlyArray<string> {+ if (!Array.isArray(value)) return Object.freeze([]);+ const out: string[] = [];+ for (const item of value) {+ if (typeof item !== "string") continue;+ const scope = item.trim();+ if (scope.length > 0) out.push(scope);+ }+ return Object.freeze([...new Set(out)]);+}++/**+ * Confirmed preferences whose `scope` is one the flow declared. Structural+ * match on the frontmatter scope token; no natural-language matching. Returns+ * `id (scope)` items, sorted for deterministic output.+ */+function listConfirmedPreferencesByScope(+ vault: string,+ scopes: ReadonlyArray<string>,+): ReadonlyArray<string> {+ if (scopes.length === 0) return Object.freeze([]);+ const wanted = new Set(scopes);+ const dir = brainDirs(vault).preferences;+ if (!existsSync(dir)) return Object.freeze([]);+ const out: string[] = [];+ for (const name of readdirSync(dir).toSorted()) {+ if (!name.endsWith(".md")) continue;+ try {+ const pref = parsePreference(join(dir, name));+ if (+ pref.status === BRAIN_PREFERENCE_STATUS.confirmed &&+ pref.scope !== undefined &&+ wanted.has(pref.scope)+ ) {+ out.push(`${pref.id} (${pref.scope})`);+ }+ } catch {+ continue;+ }+ }+ return Object.freeze(out);+}+export function buildAttentionContextBlock(vault: string,flowIds: ReadonlyArray<string>,diff --git a/src/core/brain/derived-fact.ts b/src/core/brain/derived-fact.tsnew file mode 100644index 00000000..ef1189bc--- /dev/null+++ b/src/core/brain/derived-fact.ts@@ -0,0 +1,118 @@+/**+ * Derived-fact synthesis with premise provenance (Knowledge Provenance suite).+ *+ * A derived fact is a second-order conclusion ("because A and B, therefore C")+ * the calling agent reasons out from existing premise preferences. OSB is+ * provider-agnostic and runs no model: the agent supplies the conclusion and+ * names its premises; OSB owns the deterministic half - it validates that each+ * premise preference exists, then commits the derived fact as an unconfirmed+ * preference carrying a `deduced`/`inferred` provenance level and premise+ * wikilinks in `evidenced_by`.+ *+ * Recall trusts an operator-stated rule above a machine-derived one; the+ * provenance level is what makes that ordering possible (see+ * provenance/provenance.ts and the recall trust-ordering helper).+ */++import { existsSync } from "node:fs";++import { loadBrainConfig, DEFAULT_BRAIN_CONFIG } from "./policy.ts";+import { preferencePath } from "./paths.ts";+import { writePreference } from "./preference.ts";+import { isoSecond } from "./time.ts";+import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";++export interface DeriveFactInput {+ readonly slug: string;+ readonly topic: string;+ readonly principle: string;+ /** Premise preference ids (`pref-<slug>` or bare `<slug>`), at least one. */+ readonly premises: readonly string[];+ /** Trust level of the derivation: `deduced` (entailed) or `inferred` (pattern). */+ readonly level: ProvenanceLevel;+}++export interface DeriveFactOptions {+ readonly now: Date;+}++export interface DeriveFactResult {+ readonly id: string;+}++/** A derived-fact request failed validation; nothing was written. */+export class DeriveFactError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "DeriveFactError";+ }+}++/** Strip a leading `pref-` so a premise can be given as an id or a bare slug. */+function premiseSlug(premise: string): string {+ const trimmed = premise.trim();+ return trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;+}++function addDays(date: Date, days: number): Date {+ const next = new Date(date.getTime());+ next.setUTCDate(next.getUTCDate() + days);+ return next;+}++function unconfirmedWindowDays(vault: string): number {+ try {+ return loadBrainConfig(vault).dream.unconfirmed_window_days;+ } catch {+ return DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days;+ }+}++/**+ * Commit a derived fact. Validates the level is a derivation (not `stated`)+ * and that every premise preference exists, then writes an unconfirmed+ * preference with the provenance level and premise wikilinks. Throws+ * {@link DeriveFactError} with no write on any validation failure.+ */+export function deriveFact(+ vault: string,+ input: DeriveFactInput,+ opts: DeriveFactOptions,+): DeriveFactResult {+ const level = asProvenanceLevel(input.level);+ if (level === null || level === "stated") {+ throw new DeriveFactError(+ `a derived fact must be 'deduced' or 'inferred', not ${JSON.stringify(input.level)}`,+ );+ }+ if (!input.slug.trim()) throw new DeriveFactError("derived fact missing slug");+ if (!input.topic.trim()) throw new DeriveFactError("derived fact missing topic");+ if (!input.principle.trim()) throw new DeriveFactError("derived fact missing principle");+ if (input.premises.length === 0) {+ throw new DeriveFactError("a derived fact must cite at least one premise");+ }++ const evidencedBy: string[] = [];+ for (const premise of input.premises) {+ const slug = premiseSlug(premise);+ if (!slug) throw new DeriveFactError("premise id must not be empty");+ if (!existsSync(preferencePath(vault, slug))) {+ throw new DeriveFactError(`premise preference not found: ${JSON.stringify(premise)}`);+ }+ evidencedBy.push(`[[pref-${slug}]]`);+ }++ const now = opts.now;+ writePreference(vault, {+ slug: input.slug,+ topic: input.topic,+ principle: input.principle,+ created_at: isoSecond(now),+ unconfirmed_until: isoSecond(addDays(now, unconfirmedWindowDays(vault))),+ status: "unconfirmed",+ evidenced_by: evidencedBy,+ provenance: level,+ });++ return { id: `pref-${input.slug.trim()}` };+}diff --git a/src/core/brain/ingest/ingest.ts b/src/core/brain/ingest/ingest.tsnew file mode 100644index 00000000..5a01cdca--- /dev/null+++ b/src/core/brain/ingest/ingest.ts@@ -0,0 +1,142 @@+/**+ * Source-ingest pipeline (Knowledge Provenance suite).+ *+ * Turns one text-bearing source (a document, note, or URL's text) into+ * cross-referenced Brain knowledge: the entities and concepts it mentions+ * become registry pages, and a per-source summary page links back to the raw+ * artifact, lists the entities it introduced, and lists its connections to+ * material already in the brain.+ *+ * Provider-agnostic: the calling agent extracts the entities/relations and+ * writes the prose summary; this pipeline never runs a model. OSB owns the+ * deterministic half - routing the extraction through the shared intake+ * primitive, stamping provenance, and committing the summary page idempotently+ * (one source path maps to one summary page, rewritten in place on re-ingest,+ * never duplicated). Text-bearing sources only: no OCR, binary, or media path.+ *+ * The connections list is derived, not guessed: an entity that ALREADY existed+ * before this ingest (the intake reports it as updated, not created) is a+ * genuine connection to prior material; a freshly created entity is not.+ */++import { existsSync, mkdirSync } from "node:fs";+import { dirname, relative } from "node:path";++import type { FrontmatterMap } from "../../types.ts";+import { canonicalNotePath } from "../../path-safety.ts";+import { parseFrontmatter, slugify, writeFrontmatterAtomic } from "../../vault.ts";+import { isoSecond } from "../time.ts";+import { sourcePagePath } from "../paths.ts";+import { intakeExtraction, type ExtractionIntake } from "../intake/extract-intake.ts";+import {+ renderProvenanceSection,+ sourceIdentityHash,+ type Provenance,+} from "../provenance/provenance.ts";++/** Frontmatter `kind:` marker of an ingested source summary page. */+export const BRAIN_SOURCE_KIND = "brain-source";++export interface IngestSourceInput {+ /** Source identity - a vault-relative path or a URL. Canonicalized on write. */+ readonly sourcePath: string;+ /** Agent-written summary prose for the source. */+ readonly summary: string;+ /** The entities + relations the agent extracted from the source. */+ readonly extraction: ExtractionIntake;+}++export interface IngestSourceOptions {+ readonly agent: string;+ readonly now: Date;+}++export interface IngestSourceResult {+ /** Vault-relative path of the summary page. */+ readonly summaryPath: string;+ /** `false` when the summary page already existed and was rewritten. */+ readonly created: boolean;+ /** Entity ids newly created by this ingest. */+ readonly entitiesCreated: readonly string[];+ /** Entity ids that already existed and were touched. */+ readonly entitiesUpdated: readonly string[];+ /** Pre-existing entity ids this source connected to (its connections). */+ readonly connections: readonly string[];+}++function renderLinkSection(heading: string, ids: readonly string[]): string {+ if (ids.length === 0) return "";+ return [`## ${heading}`, "", ...ids.map((id) => `- [[${id}]]`)].join("\n");+}++/**+ * Ingest one source: intake its extracted entities/relations, then write the+ * per-source summary page with a Sources backlink, an entity list, and a+ * connections-to-existing-notes list. Idempotent on the source path.+ */+export function ingestSource(+ vault: string,+ input: IngestSourceInput,+ opts: IngestSourceOptions,+): IngestSourceResult {+ const canonicalSource = canonicalNotePath(input.sourcePath);+ const sourceLink = `[[${canonicalSource}]]`;+ const provenance: Provenance = { level: "stated", sources: [sourceLink], premises: [] };++ const intake = intakeExtraction(vault, input.extraction, {+ agent: opts.agent,+ now: opts.now,+ provenance,+ });+ const connections = intake.entitiesUpdated;+ const allEntities = [...intake.entitiesCreated, ...intake.entitiesUpdated];++ // The page filename keys on the source-identity hash, not just the slug:+ // two distinct non-ASCII / symbol-only source paths can slugify to the same+ // fallback, which would silently clobber one summary with another. A hash+ // suffix keeps distinct sources distinct while staying idempotent (the same+ // source path always yields the same hash, hence the same file).+ const sourceHash = sourceIdentityHash([canonicalSource]);+ const absPath = sourcePagePath(vault, `${slugify(canonicalSource)}-${sourceHash.slice(0, 12)}`);+ const existed = existsSync(absPath);+ const stamp = isoSecond(opts.now);+ // Preserve the original created_at on a re-ingest; bump updated_at.+ const createdAt = existed ? readCreatedAt(absPath, stamp) : stamp;++ const meta: FrontmatterMap = {+ kind: BRAIN_SOURCE_KIND,+ source_path: canonicalSource,+ source_hash: sourceHash,+ provenance: provenance.level,+ created_at: createdAt,+ updated_at: stamp,+ tags: ["brain", "brain/source"],+ };++ const body = [+ input.summary.trim(),+ renderProvenanceSection(provenance),+ renderLinkSection("Entities", allEntities),+ renderLinkSection("Connections to existing notes", connections),+ ]+ .filter((section) => section.length > 0)+ .join("\n\n");++ mkdirSync(dirname(absPath), { recursive: true });+ writeFrontmatterAtomic(absPath, meta, body, { overwrite: true });++ return {+ summaryPath: canonicalNotePath(relative(vault, absPath)),+ created: !existed,+ entitiesCreated: intake.entitiesCreated,+ entitiesUpdated: intake.entitiesUpdated,+ connections,+ };+}++/** Read a stable `created_at` from an existing summary page, else fall back. */+function readCreatedAt(absPath: string, fallback: string): string {+ const [meta] = parseFrontmatter(absPath);+ const value = meta["created_at"];+ return typeof value === "string" && value.length > 0 ? value : fallback;+}diff --git a/src/core/brain/intake/extract-intake.ts b/src/core/brain/intake/extract-intake.tsnew file mode 100644index 00000000..8e0368b8--- /dev/null+++ b/src/core/brain/intake/extract-intake.ts@@ -0,0 +1,175 @@+/**+ * Extraction-intake primitive (shared lib a of the Knowledge Provenance+ * suite).+ *+ * One validated, idempotent path turns an agent-supplied typed extraction+ * (entities + typed relations) into entity-registry records. Both the+ * source-ingest pipeline and on-write NER route through this primitive, so+ * entity intake is implemented and tested once.+ *+ * Provider-agnostic boundary: the model that produced the extraction lives on+ * the agent side of the MCP/CLI boundary. This primitive never calls a model.+ * It validates the typed payload, refuses a malformed one BEFORE writing+ * anything (no partial-write fabrication), and commits through the registry's+ * own duplicate-refusing `upsertEntity` / `relateEntities`.+ *+ * Provenance: when the caller supplies a {@link Provenance}, its `## Sources`+ * section is stamped into the body of each NEWLY CREATED entity (via the+ * shared provenance primitive). An entity that already exists keeps its body+ * untouched - the per-source summary page (the ingest pipeline) carries the+ * authoritative cross-source citation list, so an entity page cites the+ * source that first introduced it without being clobbered on every later+ * mention.+ */++import { isKnownRelation, normalizeRelation } from "../../graph/relation-vocab.ts";+import { validateEntityCategory, normalizeEntityName } from "../entities/canonical.ts";+import { getEntity, relateEntities, upsertEntity } from "../entities/registry.ts";+import { renderProvenanceSection, type Provenance } from "../provenance/provenance.ts";++/** One entity the agent extracted from a source. */+export interface IntakeEntity {+ readonly category: string;+ readonly name: string;+ readonly aliases?: readonly string[];+ /** Optional confidence label passed through to the registry verbatim. */+ readonly confidence?: string;+}++/** One typed relation between two extracted entities, referenced by name. */+export interface IntakeRelation {+ readonly from: string;+ readonly fromCategory?: string;+ readonly relation: string;+ readonly to: string;+ readonly toCategory?: string;+}++/** A typed extraction the agent supplies for intake. */+export interface ExtractionIntake {+ readonly entities: readonly IntakeEntity[];+ readonly relations?: readonly IntakeRelation[];+}++export interface IntakeOptions {+ /** Agent identity stamped as the entity `source_agent`. */+ readonly agent: string;+ /** Injected clock for deterministic stamps. */+ readonly now: Date;+ /** When set, its Sources section is stamped into newly created entity bodies. */+ readonly provenance?: Provenance;+}++export interface IntakeResult {+ /** Ids of entities created by this intake. */+ readonly entitiesCreated: readonly string[];+ /** Ids of entities that already existed and were touched. */+ readonly entitiesUpdated: readonly string[];+ /** Count of relations applied (idempotent; an already-linked edge is a no-op). */+ readonly relationsApplied: number;+}++/** A typed extraction failed structural validation; nothing was written. */+export class IntakeValidationError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "IntakeValidationError";+ }+}++/** Validate the whole payload before any write, so a bad intake never writes. */+function validateIntake(intake: ExtractionIntake): void {+ const declared = new Set<string>();+ for (const entity of intake.entities) {+ if (!normalizeEntityName(entity.name)) {+ throw new IntakeValidationError("entity name must not be empty");+ }+ try {+ validateEntityCategory(entity.category);+ } catch (cause) {+ const reason = cause instanceof Error ? cause.message : String(cause);+ throw new IntakeValidationError(+ `invalid entity category ${JSON.stringify(entity.category)}: ${reason}`,+ );+ }+ declared.add(normalizeEntityName(entity.name));+ }+ for (const rel of intake.relations ?? []) {+ if (!isKnownRelation(normalizeRelation(rel.relation))) {+ throw new IntakeValidationError(+ `unknown relation ${JSON.stringify(rel.relation)} - see relation-vocab.ts`,+ );+ }+ const from = normalizeEntityName(rel.from);+ const to = normalizeEntityName(rel.to);+ if (!from || !to) {+ throw new IntakeValidationError("relation endpoints must not be empty");+ }+ if (from === to) {+ throw new IntakeValidationError(`relation cannot link ${JSON.stringify(rel.from)} to itself`);+ }+ if (!declared.has(from) || !declared.has(to)) {+ throw new IntakeValidationError(+ `relation endpoint not declared among intake entities: ${JSON.stringify(+ declared.has(from) ? rel.to : rel.from,+ )}`,+ );+ }+ }+}++/**+ * Intake a typed extraction into the entity registry. Validates the full+ * payload first (throwing {@link IntakeValidationError} with no write on+ * failure), then upserts entities and applies relations idempotently.+ */+export function intakeExtraction(+ vault: string,+ intake: ExtractionIntake,+ opts: IntakeOptions,+): IntakeResult {+ validateIntake(intake);++ const provenanceSection = opts.provenance ? renderProvenanceSection(opts.provenance) : "";++ const entitiesCreated: string[] = [];+ const entitiesUpdated: string[] = [];++ for (const entity of intake.entities) {+ const category = validateEntityCategory(entity.category);+ const existing = getEntity(vault, { category, query: entity.name });+ // Stamp provenance into the body only when creating the page, so a later+ // mention of the same entity does not overwrite its first citation.+ const body =+ existing === null && provenanceSection+ ? `# ${entity.name.trim()}\n\n${provenanceSection}`+ : undefined;+ const res = upsertEntity(vault, {+ category,+ name: entity.name,+ ...(entity.aliases !== undefined ? { aliases: entity.aliases } : {}),+ agent: opts.agent,+ now: opts.now,+ ...(entity.confidence !== undefined ? { confidence: entity.confidence } : {}),+ ...(body !== undefined ? { body } : {}),+ });+ if (res.created) entitiesCreated.push(res.entity.id);+ else entitiesUpdated.push(res.entity.id);+ }++ let relationsApplied = 0;+ for (const rel of intake.relations ?? []) {+ relateEntities(vault, {+ from: {+ query: rel.from,+ ...(rel.fromCategory !== undefined ? { category: rel.fromCategory } : {}),+ },+ relation: rel.relation,+ to: { query: rel.to, ...(rel.toCategory !== undefined ? { category: rel.toCategory } : {}) },+ now: opts.now,+ });+ relationsApplied += 1;+ }++ return { entitiesCreated, entitiesUpdated, relationsApplied };+}diff --git a/src/core/brain/owner-scoped-facts.ts b/src/core/brain/owner-scoped-facts.tsnew file mode 100644index 00000000..019ac54c--- /dev/null+++ b/src/core/brain/owner-scoped-facts.ts@@ -0,0 +1,35 @@+/**+ * Owner-scoped fact visibility (Knowledge Provenance suite).+ *+ * A preference may declare an `owner:` token. When several agents write to one+ * brain, owner-scoped recall keeps each owner's facts separate while shared+ * (ownerless) facts stay visible to all. This module is the fact-layer+ * application of the v1.6 owner-visibility model - it REUSES+ * `src/core/graph/agent-scope.ts` (pageOwner / isOwnerVisible) rather than+ * reimplementing the rule, so the fact layer and the v1.6 search agent-scope+ * share one visibility definition. It is wired into `brain_query` (the+ * per-request fact-recall surface); only preferences carry an `owner`.+ *+ * The default is byte-identical: when no scope is requested (null), every fact+ * is visible exactly as today.+ */++import { isOwnerVisible, pageOwner } from "../graph/agent-scope.ts";+import type { BrainPreference } from "./types.ts";++/** The normalized owner token of a preference, or null when ownerless. */+export function preferenceOwner(pref: Pick<BrainPreference, "owner">): string | null {+ return pageOwner({ owner: pref.owner ?? "" });+}++/**+ * Whether a preference is visible under a requested owner scope. A null scope+ * (no scope requested) makes everything visible; an ownerless fact is always+ * visible; an owned fact is visible only to its own normalized scope.+ */+export function isPreferenceVisible(+ pref: Pick<BrainPreference, "owner">,+ requestedScope: string | null,+): boolean {+ return isOwnerVisible(preferenceOwner(pref), requestedScope);+}diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.tsindex 3bf485f5..51ef1c2b 100644--- a/src/core/brain/paths.ts+++ b/src/core/brain/paths.ts@@ -53,6 +53,10 @@ export const BRAIN_PROCEDURAL_MEMORY_REL = posix.join(BRAIN_ROOT_REL, "proceduraexport const BRAIN_ATTENTION_REL = posix.join(BRAIN_ROOT_REL, "attention");export const BRAIN_LOG_REL = posix.join(BRAIN_ROOT_REL, "log");export const BRAIN_ENTITIES_REL = posix.join(BRAIN_ROOT_REL, "entities");+/** Ingested source summary pages: `Brain/sources/src-<slug>.md` (v1.7.0). */+export const BRAIN_SOURCES_REL = posix.join(BRAIN_ROOT_REL, "sources");+/** Cited research report pages: `Brain/reports/<date>-<slug>.md` (v1.7.0). */+export const BRAIN_REPORTS_REL = posix.join(BRAIN_ROOT_REL, "reports");export const BRAIN_SNAPSHOTS_REL = posix.join(BRAIN_ROOT_REL, ".snapshots");/*** Ephemeral MCP tool-result artifacts (v0.18.0). Dot-directory so the@@ -158,6 +162,19 @@ export function preferencePath(vault: string, slug: string): string {return ensureInsideVault(join(brainDirs(vault).preferences, `pref-${s}.md`), vault);}+/** Ingested source summary page: `Brain/sources/src-<slug>.md`. */+export function sourcePagePath(vault: string, slug: string): string {+ const s = validateSlug(slug);+ return ensureInsideVault(join(vault, BRAIN_SOURCES_REL, `src-${s}.md`), vault);+}++/** Cited research report page: `Brain/reports/<date>-<slug>.md`. */+export function reportPagePath(vault: string, date: string, slug: string): string {+ const d = validateIsoDate(date);+ const s = validateSlug(slug);+ return ensureInsideVault(join(vault, BRAIN_REPORTS_REL, `${d}-${s}.md`), vault);+}+/*** Per-preference edit-history sidecar: `Brain/preferences/pref-<slug>.history.jsonl`.* Lives next to the preference file; never enters the search indexdiff --git a/src/core/brain/policy.ts b/src/core/brain/policy.tsindex 2a06d5a8..53f59172 100644--- a/src/core/brain/policy.ts+++ b/src/core/brain/policy.ts@@ -119,6 +119,9 @@ export const BRAIN_GUARDRAIL_DEFAULTS: ResolvedBrainGuardrailConfig = Object.frepromotion_min_age_days: 0,instruction_file_max_lines: 200,untrusted_source_delimiting: false,+ derived_fact_synthesis: false,+ provenance_trust_ordering: false,+ owner_scoped_facts: false,}) as ResolvedBrainGuardrailConfig;/**@@ -140,6 +143,11 @@ export function resolveGuardrails(cfg: BrainConfig): ResolvedBrainGuardrailConfig.instruction_file_max_lines ?? BRAIN_GUARDRAIL_DEFAULTS.instruction_file_max_lines,untrusted_source_delimiting:g.untrusted_source_delimiting ?? BRAIN_GUARDRAIL_DEFAULTS.untrusted_source_delimiting,+ derived_fact_synthesis:+ g.derived_fact_synthesis ?? BRAIN_GUARDRAIL_DEFAULTS.derived_fact_synthesis,+ provenance_trust_ordering:+ g.provenance_trust_ordering ?? BRAIN_GUARDRAIL_DEFAULTS.provenance_trust_ordering,+ owner_scoped_facts: g.owner_scoped_facts ?? BRAIN_GUARDRAIL_DEFAULTS.owner_scoped_facts,};}@@ -992,6 +1000,9 @@ export function validateBrainConfigDetailed(promotion_min_age_days?: number;instruction_file_max_lines?: number;untrusted_source_delimiting?: boolean;+ derived_fact_synthesis?: boolean;+ provenance_trust_ordering?: boolean;+ owner_scoped_facts?: boolean;} = {};if ("promotion_min_signals" in rawMap) {@@ -1045,6 +1056,25 @@ export function validateBrainConfigDetailed(}partial.untrusted_source_delimiting = flag;}+ // Knowledge Provenance opt-in boolean flags (v1.7). Same shape as+ // untrusted_source_delimiting: present β must be boolean, else hard error.+ for (const key of [+ "derived_fact_synthesis",+ "provenance_trust_ordering",+ "owner_scoped_facts",+ ] as const) {+ if (key in rawMap) {+ const flag = rawMap[key];+ if (typeof flag !== "boolean") {+ throw new BrainConfigError(+ `must be a boolean; got ${describe(flag)}`,+ `guardrails.${key}`,+ source,+ );+ }+ partial[key] = flag;+ }+ }// Forward-compat: unknown sub-keys under `guardrails:` β warning.const knownGuardrailKeys = new Set([@@ -1053,6 +1083,9 @@ export function validateBrainConfigDetailed("promotion_min_age_days","instruction_file_max_lines","untrusted_source_delimiting",+ "derived_fact_synthesis",+ "provenance_trust_ordering",+ "owner_scoped_facts",]);for (const key of Object.keys(rawMap)) {if (!knownGuardrailKeys.has(key)) {diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.tsindex ff312bfd..b6848595 100644--- a/src/core/brain/preference.ts+++ b/src/core/brain/preference.ts@@ -47,6 +47,7 @@ import {type BrainSchemaVocabulary,} from "./schema-vocab.ts";import { brainDirs, preferencePath, retiredPath, validateSlug } from "./paths.ts";+import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";import { sanitisePrinciple } from "./text/sanitize-principle.ts";import {BRAIN_CONFIDENCE,@@ -102,6 +103,20 @@ export interface WritePreferenceInput {readonly evidenced_by: ReadonlyArray<string>;readonly confirmed_at?: string | null;readonly scope?: string;+ /**+ * Optional owner token (Knowledge Provenance suite, v1.7). When set, the+ * fact is owner-private: owner-scoped recall returns it only to its owner,+ * while ownerless facts stay shared. Stored verbatim; normalized for+ * comparison by the shared owner-visibility model.+ */+ readonly owner?: string;+ /**+ * Optional provenance trust level (Knowledge Provenance suite, v1.7).+ * Absent reads as `stated` (operator-asserted) for every existing+ * preference. A derived fact is written `deduced` or `inferred` with its+ * premise links in `evidenced_by`.+ */+ readonly provenance?: ProvenanceLevel;readonly applied_count?: number;readonly violated_count?: number;readonly last_evidence_at?: string | null;@@ -401,6 +416,12 @@ function preferenceFrontmatter(input: WritePreferenceInput, id: string): Frontmaif (input.revision !== undefined) metadata["_revision"] = input.revision;if (input.content_hash) metadata["_content_hash"] = input.content_hash;if (input.scope?.trim()) metadata["scope"] = input.scope.trim();+ if (input.owner?.trim()) metadata["owner"] = input.owner.trim();+ // Only emit a non-default provenance; absent reads as `stated`, so an+ // existing preference stays byte-identical.+ if (input.provenance !== undefined && input.provenance !== "stated") {+ metadata["provenance"] = input.provenance;+ }if (input.supersedes?.trim()) metadata["supersedes"] = input.supersedes.trim();if (input.aliases && input.aliases.length > 0) {metadata["aliases"] = [...input.aliases];@@ -625,6 +646,8 @@ export function parsePreference(const evidenced_by = optionalStringArray(meta, "evidenced_by");const confirmed_at = optionalNullableString(meta, "confirmed_at");const last_evidence_at = optionalNullableString(meta, "last_evidence_at");+ // Provenance level: validated through the shared narrowing guard, never cast.+ const provenance = asProvenanceLevel(meta["provenance"]);const result: BrainPreference = {kind: "brain-preference",@@ -650,6 +673,10 @@ export function parsePreference(...(optionalScalarString(meta, "scope") !== undefined? { scope: optionalScalarString(meta, "scope") }: {}),+ ...(optionalScalarString(meta, "owner") !== undefined+ ? { owner: optionalScalarString(meta, "owner") }+ : {}),+ ...(provenance !== null ? { provenance } : {}),...(optionalScalarString(meta, "freshness_trend") !== undefined? { freshness_trend: optionalScalarString(meta, "freshness_trend") }: {}),diff --git a/src/core/brain/provenance/provenance.ts b/src/core/brain/provenance/provenance.tsnew file mode 100644index 00000000..ce04d6c7--- /dev/null+++ b/src/core/brain/provenance/provenance.ts@@ -0,0 +1,117 @@+/**+ * Provenance / citation primitive (shared lib b of the Knowledge Provenance+ * suite).+ *+ * A piece of knowledge in the brain should carry its origin. Three+ * generation-bearing features stamp their output through this one module so+ * the representation is uniform and tested in a single place:+ * - the source-ingest pipeline (a page built from a source document),+ * - the research pipeline (a report whose findings cite their sources),+ * - derived-fact synthesis (a fact inferred from premise facts).+ *+ * What this module owns:+ * - {@link ProvenanceLevel} - the trust band (stated > deduced > inferred),+ * - {@link asProvenanceLevel} - a narrowing guard (no `as` cast) so a level+ * read from frontmatter is validated, not assumed,+ * - {@link provenanceTrustRank} - the ordering recall uses to trust an+ * operator-stated rule above a machine-inferred one,+ * - {@link renderProvenanceSection} - the canonical `## Sources` /+ * `## Premises` body markdown,+ * - {@link sourceIdentityHash} - a deterministic identity hash for+ * idempotent dedup of an ingested source.+ *+ * What it deliberately does NOT own: any page's frontmatter schema. A+ * preference, an entity page, and a report each serialize the level into+ * their own frontmatter and parse it back through {@link asProvenanceLevel}.+ * Keeping the primitive decoupled from a specific record shape is what lets+ * all three features share it (single responsibility).+ *+ * Language-agnostic: the level is a fixed structural token set, never derived+ * from natural-language vocabulary.+ */++import { createHash } from "node:crypto";++/**+ * Trust band of a piece of knowledge, ordered most-trusted first:+ * - `stated` - asserted by the operator (or promoted from operator signals),+ * - `deduced` - a logically-entailed conclusion from stated premises,+ * - `inferred` - a machine-generalized pattern, the least authoritative.+ */+export type ProvenanceLevel = "stated" | "deduced" | "inferred";++/** Every level exactly once, most-trusted first. The trust rank is the index. */+export const PROVENANCE_LEVELS: readonly ProvenanceLevel[] = Object.freeze([+ "stated",+ "deduced",+ "inferred",+]);++/**+ * Narrow an arbitrary value to a {@link ProvenanceLevel}, or null when it is+ * not one. Case- and whitespace-insensitive. Returns null for non-strings so+ * a frontmatter read never needs an `as` cast to satisfy the type.+ */+export function asProvenanceLevel(value: unknown): ProvenanceLevel | null {+ if (typeof value !== "string") return null;+ const token = value.trim().toLowerCase();+ for (const level of PROVENANCE_LEVELS) {+ if (level === token) return level;+ }+ return null;+}++/**+ * Trust rank: the position of the level in {@link PROVENANCE_LEVELS}. Lower is+ * more trusted (`stated` = 0). Recall sorts ascending by this rank so that an+ * operator-stated rule outranks a machine-inferred one.+ */+export function provenanceTrustRank(level: ProvenanceLevel): number {+ return PROVENANCE_LEVELS.indexOf(level);+}++/** Provenance stamped onto a generated page or fact. */+export interface Provenance {+ /** Trust band of the knowledge this provenance describes. */+ readonly level: ProvenanceLevel;+ /** Wikilinks to the external source artifacts the knowledge was built from. */+ readonly sources: readonly string[];+ /** Wikilinks to the premise facts a derived fact was inferred from. */+ readonly premises: readonly string[];+}++const HASH_SEPARATOR = "\n";++/**+ * Deterministic identity hash of an ingested source, for idempotent dedup.+ * The parts (e.g. a source path plus a part identifier) are trimmed and+ * newline-joined before hashing, so the same logical source always yields the+ * same 64-char lowercase hex digest regardless of incidental whitespace.+ */+export function sourceIdentityHash(parts: readonly string[]): string {+ const payload = parts.map((p) => p.trim()).join(HASH_SEPARATOR);+ return createHash("sha256").update(payload, "utf8").digest("hex");+}++/** Render one `## Heading\n\n- bullet` markdown block; caller order preserved. */+function renderBullets(heading: string, items: readonly string[]): string {+ return [`## ${heading}`, "", ...items.map((item) => `- ${item}`)].join("\n");+}++/**+ * Render the canonical provenance body markdown: a `## Sources` section+ * (external artifacts) followed by a `## Premises (<level>)` section (premise+ * facts), each omitted when empty. Returns the empty string when there is+ * nothing to cite. Caller ordering is preserved - no implicit sort - so the+ * output is deterministic and idempotent on identical input.+ */+export function renderProvenanceSection(prov: Provenance): string {+ const blocks: string[] = [];+ if (prov.sources.length > 0) {+ blocks.push(renderBullets("Sources", prov.sources));+ }+ if (prov.premises.length > 0) {+ blocks.push(renderBullets(`Premises (${prov.level})`, prov.premises));+ }+ return blocks.join("\n\n");+}diff --git a/src/core/brain/provenance/trust-order.ts b/src/core/brain/provenance/trust-order.tsnew file mode 100644index 00000000..798ee0ba--- /dev/null+++ b/src/core/brain/provenance/trust-order.ts@@ -0,0 +1,34 @@+/**+ * Provenance trust ordering for recall (Knowledge Provenance suite).+ *+ * When the `provenance_trust_ordering` guardrail is on, surfaced facts are+ * ordered so an operator-stated rule outranks a machine-derived one+ * (stated > deduced > inferred). The sort is stable, so facts of equal trust+ * keep their incoming order (e.g. the prior confidence ordering).+ *+ * Off by default: with the flag off the input order is returned unchanged, so+ * the surface is byte-identical.+ */++import { provenanceTrustRank, type ProvenanceLevel } from "./provenance.ts";++/** The provenance level of a record; absent reads as the most-trusted `stated`. */+export function provenanceLevelOf(record: {+ readonly provenance?: ProvenanceLevel;+}): ProvenanceLevel {+ return record.provenance ?? "stated";+}++/**+ * Stable-sort records by provenance trust (most-trusted first) when enabled.+ * Returns the input order unchanged when disabled.+ */+export function sortByProvenanceTrust<T extends { readonly provenance?: ProvenanceLevel }>(+ records: readonly T[],+ enabled: boolean,+): T[] {+ if (!enabled) return [...records];+ return [...records].toSorted(+ (a, b) => provenanceTrustRank(provenanceLevelOf(a)) - provenanceTrustRank(provenanceLevelOf(b)),+ );+}diff --git a/src/core/brain/research/research.ts b/src/core/brain/research/research.tsnew file mode 100644index 00000000..50dfc8c4--- /dev/null+++ b/src/core/brain/research/research.ts@@ -0,0 +1,158 @@+/**+ * Parameterized research pipeline (Knowledge Provenance suite).+ *+ * Turns N sources plus an agent-run synthesis into one dated, cited report+ * page in the vault. Each finding cites the source(s) that flagged it, so the+ * report is auditable back to its inputs and becomes a first-class recall+ * input itself.+ *+ * Provider-agnostic: the agent pulls the sources and writes the findings; OSB+ * runs no model. OSB owns the deterministic half - validating that every+ * finding cites at least one of the consulted sources (no uncited claims),+ * stamping provenance, and writing the report page idempotently (one+ * date+title maps to one report, rewritten in place).+ *+ * The citation constraint is the point: a finding with no source, or a finding+ * citing a source that was not consulted, is rejected rather than written as+ * an unprovenanced claim.+ */++import { existsSync, mkdirSync } from "node:fs";+import { dirname, relative } from "node:path";++import type { FrontmatterMap } from "../../types.ts";+import { canonicalNotePath } from "../../path-safety.ts";+import { slugify, writeFrontmatterAtomic } from "../../vault.ts";+import { isoDate, isoSecond } from "../time.ts";+import { reportPagePath } from "../paths.ts";+import { renderProvenanceSection, type Provenance } from "../provenance/provenance.ts";++/** Frontmatter `kind:` marker of a research report page. */+export const BRAIN_REPORT_KIND = "brain-report";++/** One finding plus the sources that flagged it. */+export interface ResearchFinding {+ readonly statement: string;+ /** Source identifiers (a subset of the consulted sources) that flagged this. */+ readonly sources: readonly string[];+}++export interface ResearchReportInput {+ readonly title: string;+ readonly findings: readonly ResearchFinding[];+ /** Every source consulted for the report. */+ readonly sources: readonly string[];+}++export interface ResearchReportOptions {+ readonly agent: string;+ readonly now: Date;+}++export interface ResearchReportResult {+ /** Vault-relative path of the report page. */+ readonly reportPath: string;+ readonly created: boolean;+ readonly findingCount: number;+}++/** A research report failed validation; nothing was written. */+export class ResearchValidationError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "ResearchValidationError";+ }+}++/** Wrap a bare source identifier in a wikilink; leave an existing one as-is. */+function asWikilink(source: string): string {+ const trimmed = source.trim();+ return trimmed.startsWith("[[") ? trimmed : `[[${canonicalNotePath(trimmed)}]]`;+}++function validate(input: ResearchReportInput): void {+ if (input.title.trim().length === 0) {+ throw new ResearchValidationError("report title must not be empty");+ }+ if (input.sources.length === 0) {+ throw new ResearchValidationError("a report must consult at least one source");+ }+ if (input.findings.length === 0) {+ throw new ResearchValidationError("a report must contain at least one finding");+ }+ const consulted = new Set(input.sources.map((s) => s.trim()));+ for (const [i, finding] of input.findings.entries()) {+ if (finding.statement.trim().length === 0) {+ throw new ResearchValidationError(`finding[${i}] statement must not be empty`);+ }+ if (finding.sources.length === 0) {+ throw new ResearchValidationError(+ `finding[${i}] must cite at least one source (no uncited claims)`,+ );+ }+ for (const src of finding.sources) {+ if (!consulted.has(src.trim())) {+ throw new ResearchValidationError(+ `finding[${i}] cites a source not in the consulted set: ${JSON.stringify(src)}`,+ );+ }+ }+ }+}++/**+ * Write a dated, cited research report. Validates the citation contract first+ * (throwing {@link ResearchValidationError} with no write on failure), then+ * writes the report page idempotently on the date+title path.+ */+export function writeResearchReport(+ vault: string,+ input: ResearchReportInput,+ opts: ResearchReportOptions,+): ResearchReportResult {+ validate(input);++ const date = isoDate(opts.now);+ const stamp = isoSecond(opts.now);+ const absPath = reportPagePath(vault, date, slugify(input.title));++ const findingLines = input.findings.map((f) => {+ const cites = f.sources.map(asWikilink).join(", ");+ return `- ${f.statement.trim()} (cites: ${cites})`;+ });+ const provenance: Provenance = {+ level: "stated",+ sources: input.sources.map(asWikilink),+ premises: [],+ };++ const body = [+ `# ${input.title.trim()}`,+ ["## Findings", "", ...findingLines].join("\n"),+ renderProvenanceSection(provenance),+ ].join("\n\n");++ const meta: FrontmatterMap = {+ kind: BRAIN_REPORT_KIND,+ title: input.title.trim(),+ report_date: date,+ provenance: provenance.level,+ source_count: input.sources.length,+ created_at: stamp,+ updated_at: stamp,+ tags: ["brain", "brain/report"],+ };++ mkdirSync(dirname(absPath), { recursive: true });+ // Idempotent on date+title: a re-run rewrites the same report page in place.+ // existsSync drives the `created` flag; an overwrite write then surfaces a+ // real I/O error directly instead of a catch masking it as a re-run.+ const created = !existsSync(absPath);+ writeFrontmatterAtomic(absPath, meta, body, { overwrite: true });++ return {+ reportPath: canonicalNotePath(relative(vault, absPath)),+ created,+ findingCount: input.findings.length,+ };+}diff --git a/src/core/brain/types.ts b/src/core/brain/types.tsindex 9a491f41..0eb42b84 100644--- a/src/core/brain/types.ts+++ b/src/core/brain/types.ts@@ -418,6 +418,13 @@ export interface BrainPreference {readonly tags: ReadonlyArray<string>;readonly topic: string;readonly scope?: string;+ /** Optional owner token (v1.7); owner-scoped recall hides it from others. */+ readonly owner?: string;+ /**+ * Provenance trust level (v1.7). Absent reads as `stated`; a derived fact+ * is `deduced` or `inferred` with its premise links in `evidenced_by`.+ */+ readonly provenance?: "stated" | "deduced" | "inferred";readonly status: BrainPreferenceStatus;readonly principle: string;/** Origin signals; fixed at creation. Wikilinks (`[[sig-...]]`). */@@ -955,6 +962,30 @@ export interface BrainGuardrailConfig {* legacy blocklist behaviour bit-identical.*/readonly untrusted_source_delimiting?: boolean;+ /**+ * Opt-in derived-fact synthesis (Knowledge Provenance suite, v1.7). When+ * `true`, the `brain_derive_fact` tool is enabled: an agent supplies a+ * second-order conclusion plus its premise preference ids, and it is+ * committed as an unconfirmed preference carrying premise links and a+ * `deduced`/`inferred` provenance level. Synthesis is agent-driven (OSB runs+ * no model); the flag gates the tool, not an automatic dream phase. Defaults+ * to `false`, so the tool refuses and no derived facts are produced.+ */+ readonly derived_fact_synthesis?: boolean;+ /**+ * Opt-in provenance trust ordering (Knowledge Provenance suite, v1.7).+ * When `true`, recall orders an operator-stated rule above a machine-+ * inferred one (stated > deduced > inferred) as a stable tiebreak.+ * Defaults to `false`, leaving recall ordering byte-identical.+ */+ readonly provenance_trust_ordering?: boolean;+ /**+ * Opt-in owner-scoped fact recall (Knowledge Provenance suite, v1.7). When+ * `true`, a fact declaring an `owner:` token is returned only to a matching+ * requested scope; ownerless facts stay shared. Defaults to `false`, so+ * recall is byte-identical when no scope is requested.+ */+ readonly owner_scoped_facts?: boolean;}/**@@ -1152,6 +1183,9 @@ export interface ResolvedBrainGuardrailConfig {readonly promotion_min_age_days: number;readonly instruction_file_max_lines: number;readonly untrusted_source_delimiting: boolean;+ readonly derived_fact_synthesis: boolean;+ readonly provenance_trust_ordering: boolean;+ readonly owner_scoped_facts: boolean;}/**diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.tsindex 3241dd4f..ad30dda4 100644--- a/src/mcp/brain-tools.ts+++ b/src/mcp/brain-tools.ts@@ -26,6 +26,10 @@ import { WORKSPACE_TOOLS } from "./brain/workspace-tools.ts";import { PROCEDURE_TOOLS } from "./brain/procedure-tools.ts";import { LANDSCAPE_TOOLS } from "./brain/landscape-tools.ts";import { HYGIENE_TOOLS } from "./brain/hygiene-tools.ts";+import { NER_TOOLS } from "./brain/ner-tools.ts";+import { INGEST_TOOLS } from "./brain/ingest-tools.ts";+import { RESEARCH_TOOLS } from "./brain/research-tools.ts";+import { DERIVE_TOOLS } from "./brain/derive-tools.ts";import type { ToolDefinition } from "./tools.ts";export { vaultRelativeSafe } from "./brain/shared.ts";@@ -47,4 +51,8 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([...PROCEDURE_TOOLS,...LANDSCAPE_TOOLS,...HYGIENE_TOOLS,+ ...NER_TOOLS,+ ...INGEST_TOOLS,+ ...RESEARCH_TOOLS,+ ...DERIVE_TOOLS,]);diff --git a/src/mcp/brain/derive-tools.ts b/src/mcp/brain/derive-tools.tsnew file mode 100644index 00000000..8b2d8e0a--- /dev/null+++ b/src/mcp/brain/derive-tools.ts@@ -0,0 +1,95 @@+/**+ * Derived-fact synthesis tool (Knowledge Provenance suite).+ *+ * The calling agent reasons a second-order conclusion from existing premise+ * preferences and submits it here. OSB runs no model: it validates that each+ * premise exists and commits the conclusion as an unconfirmed preference+ * carrying a `deduced`/`inferred` provenance level and premise wikilinks.+ *+ * Opt-in: gated by the `derived_fact_synthesis` guardrail. With the flag off+ * the tool refuses (the feature is not enabled), so no derived facts are+ * produced and the brain is unchanged.+ */++import { deriveFact, DeriveFactError } from "../../core/brain/derived-fact.ts";+import { loadGuardrailsConfigSafe } from "../../core/brain/policy.ts";+import { asProvenanceLevel } from "../../core/brain/provenance/provenance.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import type { ServerContext, ToolDefinition } from "../tools.ts";+import { coerceStr, coerceStrList } from "../coerce.ts";++const TOOL = "brain_derive_fact";++async function toolBrainDeriveFact(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ if (!loadGuardrailsConfigSafe(ctx.vault).derived_fact_synthesis) {+ throw new MCPError(+ INVALID_PARAMS,+ `${TOOL}: derived-fact synthesis is off; enable guardrails.derived_fact_synthesis in _brain.yaml`,+ );+ }++ const slug = coerceStr(args, "slug", true)!;+ const topic = coerceStr(args, "topic", true)!;+ const principle = coerceStr(args, "principle", true)!;+ const levelRaw = coerceStr(args, "level", true)!;+ const level = asProvenanceLevel(levelRaw);+ if (level === null || level === "stated") {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'level' must be 'deduced' or 'inferred'`);+ }+ const premises = coerceStrList(args, "premises");+ if (premises.length === 0) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'premises' must list at least one premise id`);+ }++ try {+ const res = deriveFact(+ ctx.vault,+ { slug, topic, principle, premises, level },+ { now: new Date() },+ );+ return { id: res.id, level, premises };+ } catch (err) {+ if (err instanceof DeriveFactError) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);+ }+ if (err instanceof MCPError) throw err;+ const reason = err instanceof Error ? err.message : String(err);+ throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);+ }+}++export const DERIVE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([+ {+ name: TOOL,+ description:+ "Commit a derived fact (a conclusion the agent reasoned from premises) as an unconfirmed preference with premise provenance. Supply `slug`, `topic`, `principle`, `premises` (ids), and `level` (deduced/inferred). OSB validates each premise exists. Opt-in: requires guardrails.derived_fact_synthesis.",+ inputSchema: {+ type: "object",+ properties: {+ slug: { type: "string", description: "Kebab slug for the derived preference." },+ topic: { type: "string", description: "Topic anchor for the derived fact." },+ principle: { type: "string", description: "The conclusion, in imperative voice." },+ premises: {+ type: "array",+ items: { type: "string" },+ description: "Premise preference ids (`pref-<slug>` or bare `<slug>`); at least one.",+ },+ level: {+ type: "string",+ enum: ["deduced", "inferred"],+ description: "'deduced' = logically entailed; 'inferred' = a generalized pattern.",+ },+ agent: {+ type: "string",+ description: "Optional agent identity override; defaults to the server-resolved name.",+ },+ },+ required: ["slug", "topic", "principle", "premises", "level"],+ additionalProperties: false,+ },+ handler: toolBrainDeriveFact,+ },+]);diff --git a/src/mcp/brain/ingest-tools.ts b/src/mcp/brain/ingest-tools.tsnew file mode 100644index 00000000..b1b89a00--- /dev/null+++ b/src/mcp/brain/ingest-tools.ts@@ -0,0 +1,114 @@+/**+ * Source-ingest tool (Knowledge Provenance suite).+ *+ * The calling agent reads a text-bearing source, extracts its entities and+ * relations, and writes a summary; it submits all of that here. OSB runs no+ * model - it routes the extraction through the shared intake primitive and+ * writes a per-source summary page that backlinks the source, lists the+ * entities it introduced, and lists its connections to pre-existing material.+ * Idempotent on the source path.+ */++import { ingestSource } from "../../core/brain/ingest/ingest.ts";+import { IntakeValidationError } from "../../core/brain/intake/extract-intake.ts";+import { resolveAgentName } from "../../core/config.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import type { ServerContext, ToolDefinition } from "../tools.ts";+import { coerceStr } from "../coerce.ts";+import { parseExtractionIntakeArgs } from "./intake-args.ts";++const TOOL = "brain_ingest_source";++async function toolBrainIngestSource(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const sourcePath = coerceStr(args, "source_path", true)!;+ const summary = coerceStr(args, "summary", true)!;+ const parsed = parseExtractionIntakeArgs(args, TOOL);+ const agent =+ parsed.agent && parsed.agent.trim().length > 0+ ? parsed.agent+ : resolveAgentName(ctx.configPath ?? undefined);++ try {+ const res = ingestSource(+ ctx.vault,+ { sourcePath, summary, extraction: parsed.intake },+ { agent, now: new Date() },+ );+ return {+ summary_path: res.summaryPath,+ created: res.created,+ entities_created: [...res.entitiesCreated],+ entities_updated: [...res.entitiesUpdated],+ connections: [...res.connections],+ };+ } catch (err) {+ if (err instanceof IntakeValidationError) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);+ }+ if (err instanceof MCPError) throw err;+ const reason = err instanceof Error ? err.message : String(err);+ throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);+ }+}++export const INGEST_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([+ {+ name: TOOL,+ description:+ "Ingest one text-bearing source into the brain. Supply `source_path` (vault path or URL), a `summary`, the extracted `entities`, and optional `relations`. OSB creates/updates entity pages and a per-source summary page that backlinks the source and lists its connections. Idempotent; no model, no OCR.",+ inputSchema: {+ type: "object",+ properties: {+ source_path: {+ type: "string",+ description: "Source identity: a vault-relative path or a URL.",+ },+ summary: {+ type: "string",+ description: "Agent-written summary prose for the source.",+ },+ entities: {+ type: "array",+ description: "Entities extracted from the source (non-empty).",+ items: {+ type: "object",+ properties: {+ category: { type: "string", description: "Entity category slug." },+ name: { type: "string", description: "Canonical display name." },+ aliases: { type: "array", items: { type: "string" } },+ confidence: { type: "string" },+ },+ required: ["category", "name"],+ additionalProperties: false,+ },+ },+ relations: {+ type: "array",+ description: "Optional typed relations between extracted entities.",+ items: {+ type: "object",+ properties: {+ from: { type: "string" },+ from_category: { type: "string" },+ relation: { type: "string" },+ to: { type: "string" },+ to_category: { type: "string" },+ },+ required: ["from", "relation", "to"],+ additionalProperties: false,+ },+ },+ agent: {+ type: "string",+ description: "Optional agent identity override; defaults to the server-resolved name.",+ },+ },+ required: ["source_path", "summary", "entities"],+ additionalProperties: false,+ },+ handler: toolBrainIngestSource,+ },+]);diff --git a/src/mcp/brain/intake-args.ts b/src/mcp/brain/intake-args.tsnew file mode 100644index 00000000..dbecbc67--- /dev/null+++ b/src/mcp/brain/intake-args.ts@@ -0,0 +1,138 @@+/**+ * Shared MCP-boundary parser for an agent-supplied extraction intake.+ *+ * The NER intake tool and the source-ingest tool both accept the same typed+ * shape - a list of extracted entities plus optional typed relations and an+ * optional source wikilink. This module validates that shape ONCE at the MCP+ * boundary (throwing INVALID_PARAMS on a malformed payload) and hands the+ * core {@link ExtractionIntake} to the shared intake primitive, so neither+ * tool reinvents the parsing.+ *+ * Validation is structural only - it never inspects natural-language content.+ * No `as` casts: every field is narrowed with a typeof/Array.isArray guard.+ */++import { INVALID_PARAMS, MCPError } from "../protocol.ts";+import type {+ ExtractionIntake,+ IntakeEntity,+ IntakeRelation,+} from "../../core/brain/intake/extract-intake.ts";+import type { Provenance } from "../../core/brain/provenance/provenance.ts";++export interface ParsedIntakeArgs {+ readonly intake: ExtractionIntake;+ /** Present when the caller named a source wikilink to cite. */+ readonly provenance?: Provenance;+ /** Optional agent identity override. */+ readonly agent?: string;+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function requiredString(value: unknown, tool: string, field: string): string {+ if (typeof value !== "string" || value.trim().length === 0) {+ throw new MCPError(INVALID_PARAMS, `${tool}: '${field}' must be a non-empty string`);+ }+ return value;+}++function optionalString(value: unknown, tool: string, field: string): string | undefined {+ if (value === undefined) return undefined;+ if (typeof value !== "string") {+ throw new MCPError(INVALID_PARAMS, `${tool}: '${field}' must be a string`);+ }+ return value;+}++function optionalStringArray(value: unknown, tool: string, field: string): string[] | undefined {+ if (value === undefined) return undefined;+ if (!Array.isArray(value)) {+ throw new MCPError(INVALID_PARAMS, `${tool}: '${field}' must be an array of strings`);+ }+ return value.map((item, i) => requiredString(item, tool, `${field}[${i}]`));+}++function parseEntity(value: unknown, tool: string, i: number): IntakeEntity {+ if (!isRecord(value)) {+ throw new MCPError(INVALID_PARAMS, `${tool}: entities[${i}] must be an object`);+ }+ const category = requiredString(value["category"], tool, `entities[${i}].category`);+ const name = requiredString(value["name"], tool, `entities[${i}].name`);+ const aliases = optionalStringArray(value["aliases"], tool, `entities[${i}].aliases`);+ const confidence = optionalString(value["confidence"], tool, `entities[${i}].confidence`);+ return {+ category,+ name,+ ...(aliases !== undefined ? { aliases } : {}),+ ...(confidence !== undefined ? { confidence } : {}),+ };+}++function parseRelation(value: unknown, tool: string, i: number): IntakeRelation {+ if (!isRecord(value)) {+ throw new MCPError(INVALID_PARAMS, `${tool}: relations[${i}] must be an object`);+ }+ const from = requiredString(value["from"], tool, `relations[${i}].from`);+ const relation = requiredString(value["relation"], tool, `relations[${i}].relation`);+ const to = requiredString(value["to"], tool, `relations[${i}].to`);+ const fromCategory = optionalString(+ value["from_category"],+ tool,+ `relations[${i}].from_category`,+ );+ const toCategory = optionalString(value["to_category"], tool, `relations[${i}].to_category`);+ return {+ from,+ relation,+ to,+ ...(fromCategory !== undefined ? { fromCategory } : {}),+ ...(toCategory !== undefined ? { toCategory } : {}),+ };+}++/**+ * Parse and structurally validate an extraction-intake payload from MCP tool+ * arguments. `entities` is required and must be a non-empty array; `relations`+ * and `source` are optional. A named `source` becomes a `stated`-level+ * provenance whose Sources section the intake stamps onto new entity pages.+ */+export function parseExtractionIntakeArgs(+ args: Record<string, unknown>,+ tool: string,+): ParsedIntakeArgs {+ const rawEntities = args["entities"];+ if (!Array.isArray(rawEntities) || rawEntities.length === 0) {+ throw new MCPError(INVALID_PARAMS, `${tool}: 'entities' must be a non-empty array`);+ }+ const entities = rawEntities.map((item, i) => parseEntity(item, tool, i));++ const rawRelations = args["relations"];+ let relations: IntakeRelation[] | undefined;+ if (rawRelations !== undefined) {+ if (!Array.isArray(rawRelations)) {+ throw new MCPError(INVALID_PARAMS, `${tool}: 'relations' must be an array`);+ }+ relations = rawRelations.map((item, i) => parseRelation(item, tool, i));+ }++ const source = optionalString(args["source"], tool, "source");+ const agent = optionalString(args["agent"], tool, "agent");++ const intake: ExtractionIntake = {+ entities,+ ...(relations !== undefined ? { relations } : {}),+ };+ const provenance: Provenance | undefined =+ source !== undefined && source.trim().length > 0+ ? { level: "stated", sources: [source], premises: [] }+ : undefined;++ return {+ intake,+ ...(provenance !== undefined ? { provenance } : {}),+ ...(agent !== undefined ? { agent } : {}),+ };+}diff --git a/src/mcp/brain/ner-tools.ts b/src/mcp/brain/ner-tools.tsnew file mode 100644index 00000000..e21a4a57--- /dev/null+++ b/src/mcp/brain/ner-tools.ts@@ -0,0 +1,123 @@+/**+ * Agent-driven entity intake (model-based NER, Knowledge Provenance suite).+ *+ * Open Second Brain is provider-agnostic: it never runs an entity-recognition+ * model. The calling agent (which owns its model) extracts entities from free+ * note text and submits them here; OSB validates the typed payload and commits+ * it through the shared extraction-intake primitive into the canonical entity+ * registry. No ML dependency is bundled.+ *+ * This is opt-in and non-blocking by construction: a plain note write never+ * triggers it. The agent invokes the tool when it wants discovered entities+ * registered, so extraction adds no latency or token cost to an ordinary save.+ * The contract is structural - the agent returns typed entity/concept records;+ * OSB never matches a natural-language entity-type word list.+ */++import { intakeExtraction, IntakeValidationError } from "../../core/brain/intake/extract-intake.ts";+import { resolveAgentName } from "../../core/config.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import type { ServerContext, ToolDefinition } from "../tools.ts";+import { parseExtractionIntakeArgs } from "./intake-args.ts";++const TOOL = "brain_intake_entities";++async function toolBrainIntakeEntities(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const parsed = parseExtractionIntakeArgs(args, TOOL);+ const agent =+ parsed.agent && parsed.agent.trim().length > 0+ ? parsed.agent+ : resolveAgentName(ctx.configPath ?? undefined);+ try {+ const result = intakeExtraction(ctx.vault, parsed.intake, {+ agent,+ now: new Date(),+ ...(parsed.provenance !== undefined ? { provenance: parsed.provenance } : {}),+ });+ return {+ entities_created: [...result.entitiesCreated],+ entities_updated: [...result.entitiesUpdated],+ relations_applied: result.relationsApplied,+ };+ } catch (err) {+ // A malformed extraction is a client-resolvable input problem, not a+ // server fault - surface it as INVALID_PARAMS, never a fabricated result.+ if (err instanceof IntakeValidationError) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);+ }+ if (err instanceof MCPError) throw err;+ const reason = err instanceof Error ? err.message : String(err);+ throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);+ }+}++export const NER_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([+ {+ name: TOOL,+ description:+ "Intake entities the agent extracted from note text into the entity registry (OSB runs no model). Supply `entities` (category, name, optional aliases/confidence), optional typed `relations` (from, relation, to), and an optional `source` wikilink cited on new pages. Validated and idempotent.",+ inputSchema: {+ type: "object",+ properties: {+ entities: {+ type: "array",+ description: "Entities discovered in the text (non-empty).",+ items: {+ type: "object",+ properties: {+ category: {+ type: "string",+ description: "Entity category slug, e.g. `people`, `concept`, `projects`.",+ },+ name: { type: "string", description: "Canonical display name." },+ aliases: {+ type: "array",+ items: { type: "string" },+ description: "Optional alternate names.",+ },+ confidence: {+ type: "string",+ description: "Optional confidence label passed through verbatim.",+ },+ },+ required: ["category", "name"],+ additionalProperties: false,+ },+ },+ relations: {+ type: "array",+ description: "Optional typed relations between the extracted entities.",+ items: {+ type: "object",+ properties: {+ from: { type: "string", description: "Source entity name." },+ from_category: { type: "string", description: "Optional source category." },+ relation: {+ type: "string",+ description: "Relation token from the relation vocabulary (e.g. `related`).",+ },+ to: { type: "string", description: "Target entity name." },+ to_category: { type: "string", description: "Optional target category." },+ },+ required: ["from", "relation", "to"],+ additionalProperties: false,+ },+ },+ source: {+ type: "string",+ description: "Optional source wikilink cited in the Sources section of new entity pages.",+ },+ agent: {+ type: "string",+ description: "Optional agent identity override; defaults to the server-resolved name.",+ },+ },+ required: ["entities"],+ additionalProperties: false,+ },+ handler: toolBrainIntakeEntities,+ },+]);diff --git a/src/mcp/brain/query-tools.ts b/src/mcp/brain/query-tools.tsindex 02d0e11c..2ca7e701 100644--- a/src/mcp/brain/query-tools.ts+++ b/src/mcp/brain/query-tools.ts@@ -40,6 +40,9 @@ import {} from "../coerce.ts";import { emitGatedTelemetry } from "../../core/brain/continuity/emit.ts";import { emitRecallTelemetry } from "../../core/brain/recall-telemetry.ts";+import { loadGuardrailsConfigSafe } from "../../core/brain/policy.ts";+import { normalizeAgentScope } from "../../core/graph/agent-scope.ts";+import { isPreferenceVisible } from "../../core/brain/owner-scoped-facts.ts";async function toolBrainQuery(ctx: ServerContext,@@ -76,6 +79,15 @@ async function toolBrainQuery(const telemetrySessionId = coerceStringOptional(args, "session_id", 512);const telemetryTurnId = coerceStringOptional(args, "turn_id", 512);const queryKind = preference !== null ? "preference" : topic !== null ? "topic" : "since";++ // Owner-scoped fact recall (Knowledge Provenance suite, v1.7). Off by+ // default: when the guardrail flag is off (or no scope is requested) the+ // scope is null and every fact is visible exactly as before.+ const requestedScope = coerceStr(args, "agent_scope", false);+ const ownerScope = loadGuardrailsConfigSafe(ctx.vault).owner_scoped_facts+ ? normalizeAgentScope(requestedScope ?? undefined)+ : null;+const startedAtMs = Date.now();const emitQueryTelemetry = (status: "ok" | "empty" | "error", resultCount: number): void => {// Lazy emit kernel (t_5d7aa7c5): gate off = thunk never runs; a@@ -100,6 +112,14 @@ async function toolBrainQuery(if (preference !== null) {try {const res = queryByPreference(ctx.vault, preference);+ // Fail closed: an owner-private fact outside the requested scope is+ // indistinguishable from absent, so it cannot leak across owners.+ // Only active preferences carry an owner; a retired record is shared.+ const prefOwner =+ res.preference.kind === "brain-preference" ? res.preference.owner : undefined;+ if (ownerScope !== null && !isPreferenceVisible({ owner: prefOwner }, ownerScope)) {+ throw new BrainNotFoundError(`preference not found: ${preference}`);+ }emitQueryTelemetry(res.evidence.length > 0 ? "ok" : "empty", res.evidence.length);return {mode: "preference",@@ -118,11 +138,19 @@ async function toolBrainQuery(const res = queryByTopic(ctx.vault, topic);const resultCount = res.signals.length + res.all_log_events.length;emitQueryTelemetry(resultCount > 0 ? "ok" : "empty", resultCount);+ const topicPrefOwner =+ res.preference && res.preference.kind === "brain-preference"+ ? res.preference.owner+ : undefined;+ const topicPrefVisible =+ res.preference !== null &&+ res.preference !== undefined &&+ (ownerScope === null || isPreferenceVisible({ owner: topicPrefOwner }, ownerScope));return {mode: "topic",topic,signals: res.signals.map(serializeSignal),- preference: res.preference ? serializePreference(res.preference) : null,+ preference: topicPrefVisible ? serializePreference(res.preference!) : null,all_log_events: res.all_log_events.map(serializeLogEntry),};}@@ -469,6 +497,11 @@ export const QUERY_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([telemetry_host: { type: "string", maxLength: 200 },session_id: { type: "string", maxLength: 512 },turn_id: { type: "string", maxLength: 512 },+ agent_scope: {+ type: "string",+ description:+ "Optional owner scope: with owner_scoped_facts on, an owner-tagged fact returns only to its own scope; ownerless facts always match. Absent = no filtering.",+ },},additionalProperties: false,},diff --git a/src/mcp/brain/research-tools.ts b/src/mcp/brain/research-tools.tsnew file mode 100644index 00000000..8f43f97f--- /dev/null+++ b/src/mcp/brain/research-tools.ts@@ -0,0 +1,133 @@+/**+ * Research-report tool (Knowledge Provenance suite).+ *+ * The agent pulls N sources and synthesizes findings; it submits the title,+ * the consulted sources, and the findings (each citing the source that flagged+ * it). OSB runs no model - it validates the citation contract and writes a+ * dated, cited report page into the vault. A finding with no source, or one+ * citing an unconsulted source, is rejected as INVALID_PARAMS.+ */++import {+ writeResearchReport,+ ResearchValidationError,+ type ResearchFinding,+} from "../../core/brain/research/research.ts";+import { resolveAgentName } from "../../core/config.ts";+import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";+import type { ServerContext, ToolDefinition } from "../tools.ts";+import { coerceStr } from "../coerce.ts";++const TOOL = "brain_research_report";++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function reqStringList(value: unknown, field: string): string[] {+ if (!Array.isArray(value) || value.length === 0) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: '${field}' must be a non-empty array of strings`);+ }+ return value.map((item, i) => {+ if (typeof item !== "string" || item.trim().length === 0) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: '${field}[${i}]' must be a non-empty string`);+ }+ return item;+ });+}++function parseFinding(value: unknown, i: number): ResearchFinding {+ if (!isRecord(value)) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: findings[${i}] must be an object`);+ }+ const statement = value["statement"];+ if (typeof statement !== "string" || statement.trim().length === 0) {+ throw new MCPError(+ INVALID_PARAMS,+ `${TOOL}: findings[${i}].statement must be a non-empty string`,+ );+ }+ const sources = reqStringList(value["sources"], `findings[${i}].sources`);+ return { statement, sources };+}++async function toolBrainResearchReport(+ ctx: ServerContext,+ args: Record<string, unknown>,+): Promise<Record<string, unknown>> {+ const title = coerceStr(args, "title", true)!;+ const sources = reqStringList(args["sources"], "sources");+ const rawFindings = args["findings"];+ if (!Array.isArray(rawFindings) || rawFindings.length === 0) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'findings' must be a non-empty array`);+ }+ const findings = rawFindings.map((item, i) => parseFinding(item, i));+ const agentArg = coerceStr(args, "agent", false);+ const agent =+ agentArg && agentArg.trim().length > 0+ ? agentArg+ : resolveAgentName(ctx.configPath ?? undefined);++ try {+ const res = writeResearchReport(+ ctx.vault,+ { title, sources, findings },+ { agent, now: new Date() },+ );+ return {+ report_path: res.reportPath,+ created: res.created,+ finding_count: res.findingCount,+ };+ } catch (err) {+ if (err instanceof ResearchValidationError) {+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`);+ }+ if (err instanceof MCPError) throw err;+ const reason = err instanceof Error ? err.message : String(err);+ throw new MCPError(INTERNAL_ERROR, `${TOOL}: ${reason}`);+ }+}++export const RESEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([+ {+ name: TOOL,+ description:+ "Write a dated, cited research report. Supply `title`, consulted `sources`, and `findings` (each citing its source). OSB rejects uncited findings, then writes one report page per date+title (idempotent). OSB runs no model.",+ inputSchema: {+ type: "object",+ properties: {+ title: { type: "string", description: "Report title (also the page slug)." },+ sources: {+ type: "array",+ items: { type: "string" },+ description: "Every source consulted (identifiers or wikilinks).",+ },+ findings: {+ type: "array",+ description: "Findings, each citing the source(s) that flagged it.",+ items: {+ type: "object",+ properties: {+ statement: { type: "string", description: "The finding text." },+ sources: {+ type: "array",+ items: { type: "string" },+ description: "Sources (a subset of `sources`) that flagged this finding.",+ },+ },+ required: ["statement", "sources"],+ additionalProperties: false,+ },+ },+ agent: {+ type: "string",+ description: "Optional agent identity override; defaults to the server-resolved name.",+ },+ },+ required: ["title", "sources", "findings"],+ additionalProperties: false,+ },+ handler: toolBrainResearchReport,+ },+]);diff --git a/src/mcp/registry-guard.ts b/src/mcp/registry-guard.tsindex 239d6173..05fb3b5b 100644--- a/src/mcp/registry-guard.ts+++ b/src/mcp/registry-guard.ts@@ -88,6 +88,10 @@ export const PREVIEW_BUDGET_EXEMPT: Readonly<Record<string, string>> = Object.frbrain_switch_vault: "write; returns a small profile ack",brain_write_session: "lifecycle ops return one fixed-shape envelope; prompts are kernel-bounded",schema_apply_mutations: "write; returns a bounded mutation receipt",+ brain_intake_entities: "write; returns created/updated id lists and a relation count",+ brain_ingest_source: "write; returns the summary path plus bounded id lists",+ brain_research_report: "write; returns the report path and a finding count",+ brain_derive_fact: "write; returns one derived preference id, its level and premises",// Bounded-by-construction reads.second_brain_capabilities: "fixed-size capability report",diff --git a/tests/core/brain/attention-standing-query.test.ts b/tests/core/brain/attention-standing-query.test.tsnew file mode 100644index 00000000..ebb84913--- /dev/null+++ b/tests/core/brain/attention-standing-query.test.ts@@ -0,0 +1,104 @@+/**+ * Operator-editable standing-query attention layer (Knowledge Provenance+ * suite). Extends the existing attention-flows mechanism with a+ * `standing_query` action: an operator declares scope tokens in a flow doc and+ * the matching confirmed preferences always surface into the assembled+ * context. Structural (scope-token) selector - language-agnostic. A vault that+ * declares no standing_query is byte-identical to today.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import { attentionFlowsDir } from "../../../src/core/brain/paths.ts";+import { writeFrontmatterAtomic } from "../../../src/core/vault.ts";+import { writePreference } from "../../../src/core/brain/preference.ts";+import {+ evaluateAttentionFlow,+ listAttentionFlows,+} from "../../../src/core/brain/attention-flows.ts";++let vault: string;+let configHome: string;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-standing-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-standing-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function writeConfirmed(slug: string, scope?: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `rule ${slug}`,+ created_at: "2026-06-01T00:00:00Z",+ unconfirmed_until: "2026-07-01T00:00:00Z",+ confirmed_at: "2026-06-02T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ ...(scope !== undefined ? { scope } : {}),+ });+}++function writeStandingFlow(scopes: string[]): void {+ writeFrontmatterAtomic(+ join(attentionFlowsDir(vault), "loops.md"),+ {+ kind: "brain-attention-flow",+ id: "loops",+ title: "Open loops",+ actions: ["standing_query"],+ standing_queries: scopes,+ status: "active",+ },+ "# Open loops",+ { overwrite: true },+ );+}++describe("standing_query attention action", () => {+ test("surfaces confirmed preferences whose scope the operator declared", () => {+ writeConfirmed("a", "commitment");+ writeConfirmed("b", "commitment");+ writeConfirmed("c", "writing");+ writeStandingFlow(["commitment"]);++ const evaluation = evaluateAttentionFlow(vault, "loops");+ const section = evaluation.sections.find((s) => s.action === "standing_query");+ expect(section).toBeDefined();+ expect(section?.items).toEqual(["pref-a (commitment)", "pref-b (commitment)"]);+ });++ test("the recipe parses the declared scope tokens", () => {+ writeStandingFlow(["commitment", "writing"]);+ const flow = listAttentionFlows(vault).find((f) => f.id === "loops");+ expect(flow?.standingQueryScopes).toEqual(["commitment", "writing"]);+ });++ test("the default flow declares no standing query (byte-identical default)", () => {+ // ensureDefaultAttentionFlows writes open-loops.md without standing_query.+ const flow = listAttentionFlows(vault).find((f) => f.id === "open-loops");+ expect(flow?.actions.includes("standing_query")).toBe(false);+ expect(flow?.standingQueryScopes).toEqual([]);+ });++ test("an empty declared scope set surfaces nothing", () => {+ writeConfirmed("a", "commitment");+ writeStandingFlow([]);+ const evaluation = evaluateAttentionFlow(vault, "loops");+ const section = evaluation.sections.find((s) => s.action === "standing_query");+ expect(section?.items).toEqual([]);+ });+});diff --git a/tests/core/brain/derived-fact.test.ts b/tests/core/brain/derived-fact.test.tsnew file mode 100644index 00000000..fe3d737d--- /dev/null+++ b/tests/core/brain/derived-fact.test.ts@@ -0,0 +1,142 @@+/**+ * Derived-fact synthesis with premise provenance (Knowledge Provenance suite).+ * The agent reasons the conclusion; OSB validates premises and commits the+ * derived fact with a deduced/inferred provenance level and premise links.+ * Tests cover the deterministic plumbing (provenance round-trip, premise+ * validation, trust ordering) - never model-generated reasoning text.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import { preferencePath } from "../../../src/core/brain/paths.ts";+import { writePreference, parsePreference } from "../../../src/core/brain/preference.ts";+import { deriveFact, DeriveFactError } from "../../../src/core/brain/derived-fact.ts";+import { sortByProvenanceTrust } from "../../../src/core/brain/provenance/trust-order.ts";+import type { BrainPreference } from "../../../src/core/brain/types.ts";++let vault: string;+let configHome: string;++const NOW = new Date("2026-06-13T12:00:00Z");++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-derive-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-derive-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function seedPremise(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `premise ${slug}`,+ created_at: "2026-06-01T00:00:00Z",+ unconfirmed_until: "2026-07-01T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ });+}++describe("provenance round-trips through write/parse", () => {+ test("an inferred level persists; absent reads as undefined (i.e. stated)", () => {+ writePreference(vault, {+ slug: "derived",+ topic: "derived-topic",+ principle: "derived rule",+ created_at: "2026-06-13T12:00:00Z",+ unconfirmed_until: "2026-07-13T12:00:00Z",+ status: "unconfirmed",+ evidenced_by: ["[[pref-a]]"],+ provenance: "inferred",+ });+ expect(parsePreference(preferencePath(vault, "derived")).provenance).toBe("inferred");++ seedPremise("plain");+ expect(parsePreference(preferencePath(vault, "plain")).provenance).toBeUndefined();+ });+});++describe("deriveFact", () => {+ test("commits a derived fact with premise links and the provenance level", () => {+ seedPremise("a");+ seedPremise("b");+ const res = deriveFact(+ vault,+ {+ slug: "because-a-and-b",+ topic: "derived",+ principle: "Therefore C",+ premises: ["pref-a", "b"],+ level: "deduced",+ },+ { now: NOW },+ );+ expect(res.id).toBe("pref-because-a-and-b");+ const pref = parsePreference(preferencePath(vault, "because-a-and-b"));+ expect(pref.provenance).toBe("deduced");+ expect(pref.status).toBe("unconfirmed");+ expect(pref.evidenced_by).toEqual(["[[pref-a]]", "[[pref-b]]"]);+ });++ test("rejects a missing premise with no write", () => {+ seedPremise("a");+ expect(() =>+ deriveFact(+ vault,+ { slug: "d", topic: "t", principle: "p", premises: ["pref-a", "ghost"], level: "inferred" },+ { now: NOW },+ ),+ ).toThrow(DeriveFactError);+ });++ test("rejects a 'stated' level (a derived fact is never operator-stated)", () => {+ seedPremise("a");+ expect(() =>+ deriveFact(+ vault,+ { slug: "d", topic: "t", principle: "p", premises: ["pref-a"], level: "stated" },+ { now: NOW },+ ),+ ).toThrow(DeriveFactError);+ });+});++const mk = (+ id: string,+ provenance?: BrainPreference["provenance"],+): { id: string; provenance?: BrainPreference["provenance"] } =>+ provenance !== undefined ? { id, provenance } : { id };++describe("sortByProvenanceTrust", () => {+ test("disabled: returns the input order unchanged (byte-identical)", () => {+ const input = [mk("x", "inferred"), mk("y", "stated")];+ expect(sortByProvenanceTrust(input, false).map((r) => r.id)).toEqual(["x", "y"]);+ });++ test("enabled: ranks stated above deduced above inferred, stably", () => {+ const input = [+ mk("inf", "inferred"),+ mk("stated-implicit"),+ mk("ded", "deduced"),+ mk("stated-explicit", "stated"),+ ];+ expect(sortByProvenanceTrust(input, true).map((r) => r.id)).toEqual([+ "stated-implicit",+ "stated-explicit",+ "ded",+ "inf",+ ]);+ });+});diff --git a/tests/core/brain/doctor-trust.test.ts b/tests/core/brain/doctor-trust.test.tsindex df5ebb8b..e79bc24a 100644--- a/tests/core/brain/doctor-trust.test.ts+++ b/tests/core/brain/doctor-trust.test.ts@@ -88,6 +88,9 @@ describe("runDoctor - trust integration", () => {promotion_min_age_days: 0,instruction_file_max_lines: 30,untrusted_source_delimiting: false,+ derived_fact_synthesis: false,+ provenance_trust_ordering: false,+ owner_scoped_facts: false,},});expect(result.instruction_file_warnings ?? []).toHaveLength(1);diff --git a/tests/core/brain/ingest/ingest.test.ts b/tests/core/brain/ingest/ingest.test.tsnew file mode 100644index 00000000..2b6f57e2--- /dev/null+++ b/tests/core/brain/ingest/ingest.test.ts@@ -0,0 +1,105 @@+/**+ * Source-ingest pipeline (Knowledge Provenance suite). One text-bearing source+ * becomes entity/concept pages plus a per-source summary page that backlinks+ * the source, lists the entities it introduced, and lists its connections to+ * pre-existing material. Idempotent on the source path. OSB runs no model -+ * the agent supplies the extraction and the summary prose.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";+import {+ getEntity,+ listEntities,+ upsertEntity,+} from "../../../../src/core/brain/entities/registry.ts";+import { ingestSource } from "../../../../src/core/brain/ingest/ingest.ts";++let vault: string;+let configHome: string;++const NOW = new Date("2026-06-13T12:00:00Z");+const LATER = new Date("2026-06-14T09:00:00Z");++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-ingest-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-ingest-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const INPUT = {+ sourcePath: "Articles/restaking-primer.md",+ summary: "An overview of restaking and its role for validators.",+ extraction: {+ entities: [+ { category: "concept", name: "Restaking" },+ { category: "concept", name: "Validators" },+ ],+ relations: [{ from: "Restaking", relation: "related", to: "Validators" }],+ },+};++function readSummary(summaryPath: string): string {+ return readFileSync(join(vault, summaryPath), "utf8");+}++describe("ingestSource", () => {+ test("creates entity pages and a summary page that backlinks the source", () => {+ const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });+ expect(res.created).toBe(true);+ expect(res.entitiesCreated).toHaveLength(2);+ expect(listEntities(vault, { category: "concept" })).toHaveLength(2);++ const md = readSummary(res.summaryPath);+ expect(md).toContain("kind: brain-source");+ expect(md).toContain("An overview of restaking");+ expect(md).toContain("## Sources");+ expect(md).toContain("[[Articles/restaking-primer.md]]");+ expect(md).toContain("## Entities");+ });++ test("lists pre-existing entities as connections, new ones only as entities", () => {+ // Seed Validators so it pre-exists; the ingest should report it as a+ // connection to existing material, while Restaking is freshly created.+ upsertEntity(vault, { category: "concept", name: "Validators", agent: "claude", now: NOW });++ const res = ingestSource(vault, INPUT, { agent: "claude", now: LATER });+ expect(res.entitiesCreated).toHaveLength(1); // Restaking+ expect(res.connections).toHaveLength(1); // Validators+ expect(res.connections[0]).toContain("validators");++ const md = readSummary(res.summaryPath);+ expect(md).toContain("## Connections to existing notes");+ });++ test("is idempotent on the source path: re-ingest rewrites, does not duplicate", () => {+ const first = ingestSource(vault, INPUT, { agent: "claude", now: NOW });+ const second = ingestSource(vault, INPUT, { agent: "claude", now: LATER });+ expect(second.created).toBe(false);+ expect(second.summaryPath).toBe(first.summaryPath);+ // created_at is preserved from the first ingest; updated_at advanced.+ expect(first.created).toBe(true);+ const md = readSummary(second.summaryPath);+ expect(md).toContain('created_at: "2026-06-13T12:00:00Z"');+ expect(md).toContain('updated_at: "2026-06-14T09:00:00Z"');+ });++ test("entity pages cite the source in their body", () => {+ const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });+ expect(res.summaryPath).toBeTruthy();+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ expect(restaking?.body).toContain("[[Articles/restaking-primer.md]]");+ });+});diff --git a/tests/core/brain/intake/extract-intake.test.ts b/tests/core/brain/intake/extract-intake.test.tsnew file mode 100644index 00000000..c97a6112--- /dev/null+++ b/tests/core/brain/intake/extract-intake.test.ts@@ -0,0 +1,169 @@+/**+ * Extraction-intake primitive (shared lib a of the Knowledge Provenance+ * suite). The single validated, idempotent path that turns an agent-supplied+ * typed extraction (entities + relations) into entity-registry records, with+ * provenance stamped on newly created pages. Shared by the source-ingest+ * pipeline and on-write NER so neither reinvents entity intake.+ *+ * The model that produced the extraction lives on the agent side of the MCP+ * boundary; this primitive never calls a model. It only validates the typed+ * payload, refuses a malformed one with no partial write, and commits through+ * the registry's own duplicate-refusing upsert.+ */++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 { getEntity, listEntities } from "../../../../src/core/brain/entities/registry.ts";+import {+ intakeExtraction,+ IntakeValidationError,+ type ExtractionIntake,+} from "../../../../src/core/brain/intake/extract-intake.ts";++let vault: string;+let configHome: string;++const NOW = new Date("2026-06-13T12:00:00Z");++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-intake-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-intake-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const SAMPLE: ExtractionIntake = {+ entities: [+ { category: "concept", name: "Restaking" },+ { category: "concept", name: "Validators", aliases: ["Validator nodes"] },+ ],+ relations: [{ from: "Restaking", relation: "related", to: "Validators" }],+};++describe("intakeExtraction - happy path", () => {+ test("creates the extracted entities and reports their ids", () => {+ const res = intakeExtraction(vault, SAMPLE, { agent: "ingest-agent", now: NOW });+ expect(res.entitiesCreated).toHaveLength(2);+ expect(res.entitiesUpdated).toHaveLength(0);+ expect(listEntities(vault, { category: "concept" })).toHaveLength(2);+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ expect(restaking?.name).toBe("Restaking");+ });++ test("applies the typed relations onto the from-entity", () => {+ const res = intakeExtraction(vault, SAMPLE, { agent: "ingest-agent", now: NOW });+ expect(res.relationsApplied).toBe(1);+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ const related = restaking?.relations.find((r) => r.relation === "related");+ expect(related?.target).toContain("validators");+ });++ test("stamps the provenance Sources section into a newly created entity body", () => {+ intakeExtraction(vault, SAMPLE, {+ agent: "ingest-agent",+ now: NOW,+ provenance: {+ level: "stated",+ sources: ["[[Articles/restaking-primer.md]]"],+ premises: [],+ },+ });+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ expect(restaking?.body).toContain("## Sources");+ expect(restaking?.body).toContain("[[Articles/restaking-primer.md]]");+ });+});++describe("intakeExtraction - idempotency", () => {+ test("a second identical intake creates nothing new and does not duplicate", () => {+ intakeExtraction(vault, SAMPLE, { agent: "ingest-agent", now: NOW });+ const second = intakeExtraction(vault, SAMPLE, { agent: "ingest-agent", now: NOW });+ expect(second.entitiesCreated).toHaveLength(0);+ expect(second.entitiesUpdated).toHaveLength(2);+ expect(listEntities(vault, { category: "concept" })).toHaveLength(2);+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ const relatedEdges = restaking?.relations.filter((r) => r.relation === "related") ?? [];+ expect(relatedEdges).toHaveLength(1);+ });++ test("does not clobber an existing entity body on update", () => {+ intakeExtraction(vault, SAMPLE, {+ agent: "ingest-agent",+ now: NOW,+ provenance: { level: "stated", sources: ["[[Articles/a.md]]"], premises: [] },+ });+ intakeExtraction(vault, SAMPLE, {+ agent: "ingest-agent",+ now: NOW,+ provenance: { level: "stated", sources: ["[[Articles/b.md]]"], premises: [] },+ });+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ // First source is preserved; the update did not overwrite the body.+ expect(restaking?.body).toContain("[[Articles/a.md]]");+ });+});++describe("intakeExtraction - validation refuses malformed payloads with no partial write", () => {+ test("rejects an empty entity name", () => {+ const bad: ExtractionIntake = { entities: [{ category: "concept", name: " " }] };+ expect(() => intakeExtraction(vault, bad, { agent: "a", now: NOW })).toThrow(+ IntakeValidationError,+ );+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("rejects an unknown relation before writing any entity", () => {+ const bad: ExtractionIntake = {+ entities: [+ { category: "concept", name: "A" },+ { category: "concept", name: "B" },+ ],+ relations: [{ from: "A", relation: "causes", to: "B" }],+ };+ expect(() => intakeExtraction(vault, bad, { agent: "a", now: NOW })).toThrow(+ IntakeValidationError,+ );+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("rejects a relation endpoint not declared among the intake entities", () => {+ const bad: ExtractionIntake = {+ entities: [{ category: "concept", name: "A" }],+ relations: [{ from: "A", relation: "related", to: "Ghost" }],+ };+ expect(() => intakeExtraction(vault, bad, { agent: "a", now: NOW })).toThrow(+ IntakeValidationError,+ );+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("rejects a self-relation", () => {+ const bad: ExtractionIntake = {+ entities: [{ category: "concept", name: "A" }],+ relations: [{ from: "A", relation: "related", to: "A" }],+ };+ expect(() => intakeExtraction(vault, bad, { agent: "a", now: NOW })).toThrow(+ IntakeValidationError,+ );+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("rejects an invalid entity category", () => {+ const bad: ExtractionIntake = { entities: [{ category: "Has Space", name: "A" }] };+ expect(() => intakeExtraction(vault, bad, { agent: "a", now: NOW })).toThrow(+ IntakeValidationError,+ );+ expect(listEntities(vault)).toHaveLength(0);+ });+});diff --git a/tests/core/brain/owner-scoped-facts.test.ts b/tests/core/brain/owner-scoped-facts.test.tsnew file mode 100644index 00000000..31e6b494--- /dev/null+++ b/tests/core/brain/owner-scoped-facts.test.ts@@ -0,0 +1,117 @@+/**+ * Owner-scoped canonical facts (Knowledge Provenance suite). A preference may+ * declare an owner; owner-scoped recall keeps each owner's facts separate+ * while shared (ownerless) facts stay visible. The rule reuses the v1.6+ * owner-visibility model. Default (no scope / flag off) is byte-identical.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";+import { brainConfigPath } from "../../../src/core/brain/paths.ts";+import { writePreference, parsePreference } from "../../../src/core/brain/preference.ts";+import { preferencePath } from "../../../src/core/brain/paths.ts";+import {+ isPreferenceVisible,+ preferenceOwner,+} from "../../../src/core/brain/owner-scoped-facts.ts";+import { QUERY_TOOLS } from "../../../src/mcp/brain/query-tools.ts";+import type { ServerContext } from "../../../src/mcp/tools.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-owner-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-owner-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++function writeOwnedPref(slug: string, topic: string, owner?: string): void {+ writePreference(vault, {+ slug,+ topic,+ principle: `principle for ${topic}`,+ created_at: "2026-06-13T12:00:00Z",+ unconfirmed_until: "2026-07-13T12:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ ...(owner !== undefined ? { owner } : {}),+ });+}++function enableOwnerScoping(): void {+ writeFileSync(+ brainConfigPath(vault),+ "schema_version: 1\nguardrails:\n owner_scoped_facts: true\n",+ );+}++const queryHandler = QUERY_TOOLS.find((t) => t.name === "brain_query")!.handler;++describe("owner-visibility filter (pure)", () => {+ test("preferenceOwner normalizes and treats blank as null", () => {+ expect(preferenceOwner({ owner: " Agent-A " })).toBe("agent-a");+ expect(preferenceOwner({ owner: "" })).toBeNull();+ expect(preferenceOwner({})).toBeNull();+ });++ test("no requested scope: everything visible (byte-identical default)", () => {+ expect(isPreferenceVisible({ owner: "agent-a" }, null)).toBe(true);+ expect(isPreferenceVisible({}, null)).toBe(true);+ });++ test("with a scope: ownerless shared, owned only to its owner", () => {+ expect(isPreferenceVisible({}, "agent-a")).toBe(true);+ expect(isPreferenceVisible({ owner: "agent-a" }, "agent-a")).toBe(true);+ expect(isPreferenceVisible({ owner: "agent-b" }, "agent-a")).toBe(false);+ });+});++describe("owner round-trips through write/parse", () => {+ test("the owner token persists in frontmatter", () => {+ writeOwnedPref("owned", "owned-topic", "Agent-A");+ const parsed = parsePreference(preferencePath(vault, "owned"));+ expect(parsed.owner).toBe("Agent-A");+ expect(preferenceOwner(parsed)).toBe("agent-a");+ });+});++describe("brain_query owner-scoped recall", () => {+ test("flag off: an owned fact is returned regardless of scope (byte-identical)", async () => {+ writeOwnedPref("owned", "owned-topic", "agent-b");+ const res = await queryHandler(ctx, { preference: "pref-owned", agent_scope: "agent-a" });+ expect(res).toMatchObject({ mode: "preference" });+ });++ test("flag on: an owned fact is hidden from a non-owner scope", async () => {+ writeOwnedPref("owned", "owned-topic", "agent-b");+ enableOwnerScoping();+ await expect(+ queryHandler(ctx, { preference: "pref-owned", agent_scope: "agent-a" }),+ ).rejects.toThrow();+ });++ test("flag on: the owner sees its own fact; shared facts always visible", async () => {+ writeOwnedPref("owned", "owned-topic", "agent-b");+ writeOwnedPref("shared", "shared-topic");+ enableOwnerScoping();+ const own = await queryHandler(ctx, { preference: "pref-owned", agent_scope: "agent-b" });+ expect(own).toMatchObject({ mode: "preference" });+ const shared = await queryHandler(ctx, { preference: "pref-shared", agent_scope: "agent-b" });+ expect(shared).toMatchObject({ mode: "preference" });+ });+});diff --git a/tests/core/brain/policy-guardrails.test.ts b/tests/core/brain/policy-guardrails.test.tsindex db90970d..e7e93c08 100644--- a/tests/core/brain/policy-guardrails.test.ts+++ b/tests/core/brain/policy-guardrails.test.ts@@ -130,3 +130,41 @@ describe("guardrails config block", () => {expect(warnings.some((w) => w.message.includes("guardrails.unknown_field"))).toBe(true);});});++describe("Knowledge Provenance opt-in flags (v1.7)", () => {+ const FLAGS = [+ "derived_fact_synthesis",+ "provenance_trust_ordering",+ "owner_scoped_facts",+ ] as const;++ test("all three default to false (byte-identical when absent)", () => {+ const resolved = resolveGuardrails(validate(HEAD).config);+ for (const flag of FLAGS) {+ expect(resolved[flag]).toBe(false);+ }+ });++ test("each flag parses true from _brain.yaml and resolves true", () => {+ for (const flag of FLAGS) {+ const { config } = validate(HEAD + `guardrails:\n ${flag}: true\n`);+ expect(config.guardrails?.[flag]).toBe(true);+ expect(resolveGuardrails(config)[flag]).toBe(true);+ }+ });++ test("a non-boolean flag value is rejected", () => {+ for (const flag of FLAGS) {+ expect(() => validate(HEAD + `guardrails:\n ${flag}: yes-please\n`)).toThrow(+ BrainConfigError,+ );+ }+ });++ test("each flag is a known key (no forward-compat warning)", () => {+ for (const flag of FLAGS) {+ const { warnings } = validate(HEAD + `guardrails:\n ${flag}: true\n`);+ expect(warnings.some((w) => w.message.includes(`guardrails.${flag}`))).toBe(false);+ }+ });+});diff --git a/tests/core/brain/provenance/provenance.test.ts b/tests/core/brain/provenance/provenance.test.tsnew file mode 100644index 00000000..28c9f51a--- /dev/null+++ b/tests/core/brain/provenance/provenance.test.ts@@ -0,0 +1,148 @@+/**+ * Provenance / citation primitive (shared lib b of the Knowledge Provenance+ * suite). Every generation-bearing feature (ingest, research report, derived+ * facts) stamps its output through this one module so source links, premise+ * links, and the stated/deduced/inferred trust level have a single canonical+ * representation, renderer, and ordering.+ *+ * The module owns the level type, its narrowing guard, the trust ranking used+ * by recall, the body-section renderer, and a deterministic source-identity+ * hash. It deliberately does NOT know any page's frontmatter schema - each+ * consumer (preference, entity page, report) serializes the level itself via+ * asProvenanceLevel, so the primitive stays decoupled and reusable.+ */++import { describe, expect, test } from "bun:test";+import { createHash } from "node:crypto";++import {+ asProvenanceLevel,+ provenanceTrustRank,+ renderProvenanceSection,+ sourceIdentityHash,+ PROVENANCE_LEVELS,+ type Provenance,+} from "../../../../src/core/brain/provenance/provenance.ts";++describe("asProvenanceLevel", () => {+ test("accepts the three canonical levels", () => {+ expect(asProvenanceLevel("stated")).toBe("stated");+ expect(asProvenanceLevel("deduced")).toBe("deduced");+ expect(asProvenanceLevel("inferred")).toBe("inferred");+ });++ test("normalizes case and surrounding whitespace", () => {+ expect(asProvenanceLevel(" Stated ")).toBe("stated");+ expect(asProvenanceLevel("INFERRED")).toBe("inferred");+ });++ test("returns null for an unknown token", () => {+ expect(asProvenanceLevel("guessed")).toBeNull();+ expect(asProvenanceLevel("")).toBeNull();+ expect(asProvenanceLevel(" ")).toBeNull();+ });++ test("returns null for a non-string value (no cast crutch)", () => {+ expect(asProvenanceLevel(42)).toBeNull();+ expect(asProvenanceLevel(null)).toBeNull();+ expect(asProvenanceLevel(undefined)).toBeNull();+ expect(asProvenanceLevel(["stated"])).toBeNull();+ });++ test("PROVENANCE_LEVELS lists every level exactly once, most-trusted first", () => {+ expect(PROVENANCE_LEVELS).toEqual(["stated", "deduced", "inferred"]);+ for (const level of PROVENANCE_LEVELS) {+ expect(asProvenanceLevel(level)).toBe(level);+ }+ });+});++describe("provenanceTrustRank", () => {+ test("ranks stated above deduced above inferred (lower rank = more trusted)", () => {+ expect(provenanceTrustRank("stated")).toBeLessThan(provenanceTrustRank("deduced"));+ expect(provenanceTrustRank("deduced")).toBeLessThan(provenanceTrustRank("inferred"));+ });++ test("rank is the position in PROVENANCE_LEVELS", () => {+ expect(provenanceTrustRank("stated")).toBe(0);+ expect(provenanceTrustRank("inferred")).toBe(PROVENANCE_LEVELS.length - 1);+ });+});++describe("sourceIdentityHash", () => {+ test("is a 64-char lowercase hex sha256, deterministic for the same parts", () => {+ const h = sourceIdentityHash(["Articles/x.md", "section-2"]);+ expect(h).toMatch(/^[0-9a-f]{64}$/);+ expect(sourceIdentityHash(["Articles/x.md", "section-2"])).toBe(h);+ });++ test("matches a direct sha256 over the trimmed, newline-joined parts", () => {+ const parts = [" Articles/x.md ", "section-2 "];+ const expected = createHash("sha256").update("Articles/x.md\nsection-2", "utf8").digest("hex");+ expect(sourceIdentityHash(parts)).toBe(expected);+ });++ test("different parts produce different hashes", () => {+ expect(sourceIdentityHash(["a"])).not.toBe(sourceIdentityHash(["b"]));+ });+});++describe("renderProvenanceSection", () => {+ test("renders a Sources section with one wikilink bullet per source", () => {+ const prov: Provenance = {+ level: "stated",+ sources: ["[[Articles/x.md]]", "[[Articles/y.md]]"],+ premises: [],+ };+ expect(renderProvenanceSection(prov)).toBe(+ ["## Sources", "", "- [[Articles/x.md]]", "- [[Articles/y.md]]"].join("\n"),+ );+ });++ test("renders a Premises section with the trust level when premises are present", () => {+ const prov: Provenance = {+ level: "inferred",+ sources: [],+ premises: ["[[pref-a]]", "[[pref-b]]"],+ };+ expect(renderProvenanceSection(prov)).toBe(+ ["## Premises (inferred)", "", "- [[pref-a]]", "- [[pref-b]]"].join("\n"),+ );+ });++ test("renders both sections, Sources before Premises, separated by a blank line", () => {+ const prov: Provenance = {+ level: "deduced",+ sources: ["[[s.md]]"],+ premises: ["[[pref-a]]"],+ };+ expect(renderProvenanceSection(prov)).toBe(+ ["## Sources", "", "- [[s.md]]", "", "## Premises (deduced)", "", "- [[pref-a]]"].join("\n"),+ );+ });++ test("returns an empty string when there are no sources and no premises", () => {+ const prov: Provenance = { level: "stated", sources: [], premises: [] };+ expect(renderProvenanceSection(prov)).toBe("");+ });++ test("is deterministic and idempotent on identical input", () => {+ const prov: Provenance = {+ level: "inferred",+ sources: ["[[s.md]]"],+ premises: ["[[pref-a]]"],+ };+ expect(renderProvenanceSection(prov)).toBe(renderProvenanceSection(prov));+ });++ test("preserves caller ordering of sources and premises (no implicit sort)", () => {+ const prov: Provenance = {+ level: "stated",+ sources: ["[[z.md]]", "[[a.md]]"],+ premises: [],+ };+ expect(renderProvenanceSection(prov)).toBe(+ ["## Sources", "", "- [[z.md]]", "- [[a.md]]"].join("\n"),+ );+ });+});diff --git a/tests/core/brain/research/research.test.ts b/tests/core/brain/research/research.test.tsnew file mode 100644index 00000000..a550adb6--- /dev/null+++ b/tests/core/brain/research/research.test.ts@@ -0,0 +1,95 @@+/**+ * Parameterized research pipeline (Knowledge Provenance suite). N sources plus+ * an agent synthesis become one dated, cited report page; each finding cites+ * the source that flagged it. OSB runs no model and rejects any uncited claim.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";+import {+ writeResearchReport,+ ResearchValidationError,+} from "../../../../src/core/brain/research/research.ts";++let vault: string;+let configHome: string;++const NOW = new Date("2026-06-13T12:00:00Z");+const LATER = new Date("2026-06-13T18:00:00Z");++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-research-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-research-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const INPUT = {+ title: "Restaking risk survey",+ sources: ["Articles/a.md", "Articles/b.md"],+ findings: [+ { statement: "Slashing risk compounds across AVSs", sources: ["Articles/a.md"] },+ {+ statement: "Withdrawal queues lengthen under stress",+ sources: ["Articles/a.md", "Articles/b.md"],+ },+ ],+};++describe("writeResearchReport", () => {+ test("writes a dated report page with per-finding citations and a Sources section", () => {+ const res = writeResearchReport(vault, INPUT, { agent: "claude", now: NOW });+ expect(res.created).toBe(true);+ expect(res.findingCount).toBe(2);+ expect(res.reportPath).toContain("2026-06-13");++ const md = readFileSync(join(vault, res.reportPath), "utf8");+ expect(md).toContain("kind: brain-report");+ expect(md).toContain("# Restaking risk survey");+ expect(md).toContain("## Findings");+ expect(md).toContain("Slashing risk compounds across AVSs (cites: [[Articles/a.md]])");+ expect(md).toContain("## Sources");+ expect(md).toContain("[[Articles/b.md]]");+ });++ test("rejects a finding with no source (no uncited claims) and writes nothing", () => {+ const bad = {+ title: "x",+ sources: ["Articles/a.md"],+ findings: [{ statement: "unsupported claim", sources: [] }],+ };+ expect(() => writeResearchReport(vault, bad, { agent: "claude", now: NOW })).toThrow(+ ResearchValidationError,+ );+ });++ test("rejects a finding citing a source that was not consulted", () => {+ const bad = {+ title: "x",+ sources: ["Articles/a.md"],+ findings: [{ statement: "claim", sources: ["Articles/ghost.md"] }],+ };+ expect(() => writeResearchReport(vault, bad, { agent: "claude", now: NOW })).toThrow(+ ResearchValidationError,+ );+ });++ test("is idempotent on date+title: a re-run rewrites the same report page", () => {+ const first = writeResearchReport(vault, INPUT, { agent: "claude", now: NOW });+ const second = writeResearchReport(vault, INPUT, { agent: "claude", now: LATER });+ expect(first.created).toBe(true);+ expect(second.created).toBe(false);+ expect(second.reportPath).toBe(first.reportPath);+ });+});diff --git a/tests/core/brain/trust/operator-summary.test.ts b/tests/core/brain/trust/operator-summary.test.tsindex 1f032268..f807e4e8 100644--- a/tests/core/brain/trust/operator-summary.test.ts+++ b/tests/core/brain/trust/operator-summary.test.ts@@ -62,6 +62,9 @@ describe("buildOperatorSummary - structural envelope", () => {promotion_min_age_days: 0,instruction_file_max_lines: 100,untrusted_source_delimiting: false,+ derived_fact_synthesis: false,+ provenance_trust_ordering: false,+ owner_scoped_facts: false,},});expect(r.instruction_file_warnings).toHaveLength(1);@@ -105,6 +108,9 @@ describe("renderOperatorSummaryMarkdown", () => {promotion_min_age_days: 0,instruction_file_max_lines: 100,untrusted_source_delimiting: false,+ derived_fact_synthesis: false,+ provenance_trust_ordering: false,+ owner_scoped_facts: false,},});const md = renderOperatorSummaryMarkdown(r);diff --git a/tests/mcp/brain-tools-parity.test.ts b/tests/mcp/brain-tools-parity.test.tsindex 540acd0a..dba780d7 100644--- a/tests/mcp/brain-tools-parity.test.ts+++ b/tests/mcp/brain-tools-parity.test.ts@@ -8,7 +8,10 @@* major/minor release decision, not a refactor.** Deliberate surface changes so far: v1.3.0 added `brain_hygiene` and- * `brain_anticipatory_context` (continuity-hygiene-freshness suite).+ * `brain_anticipatory_context` (continuity-hygiene-freshness suite); v1.7.0+ * added `brain_intake_entities`, `brain_ingest_source`,+ * `brain_research_report`, and `brain_derive_fact` (Knowledge Provenance+ * suite).*/import { describe, expect, test } from "bun:test";@@ -33,6 +36,7 @@ const FROZEN_BRAIN_TOOL_NAMES = ["brain_context_receipts","brain_dead_ends","brain_deep_synthesis",+ "brain_derive_fact","brain_doctor","brain_dream","brain_entity",@@ -41,6 +45,8 @@ const FROZEN_BRAIN_TOOL_NAMES = ["brain_health","brain_hygiene","brain_idea_discovery",+ "brain_ingest_source",+ "brain_intake_entities","brain_intent_review","brain_intention","brain_labels",@@ -56,6 +62,7 @@ const FROZEN_BRAIN_TOOL_NAMES = ["brain_query","brain_recall_telemetry","brain_recurrence",+ "brain_research_report","brain_retention","brain_review_candidates","brain_secrets",diff --git a/tests/mcp/derive-tool.test.ts b/tests/mcp/derive-tool.test.tsnew file mode 100644index 00000000..ea9af5bf--- /dev/null+++ b/tests/mcp/derive-tool.test.ts@@ -0,0 +1,95 @@+/**+ * MCP integration test for `brain_derive_fact` (Knowledge Provenance suite).+ * Opt-in behind the derived_fact_synthesis guardrail; the agent supplies the+ * conclusion and premises, OSB validates and commits with provenance.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { brainConfigPath, preferencePath } from "../../src/core/brain/paths.ts";+import { writePreference, parsePreference } from "../../src/core/brain/preference.ts";+import { DERIVE_TOOLS } from "../../src/mcp/brain/derive-tools.ts";+import { MCPError } from "../../src/mcp/protocol.ts";+import type { ServerContext } from "../../src/mcp/tools.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-derive-tool-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-derive-tool-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const handler = DERIVE_TOOLS[0]!.handler;++function enableDerivation(): void {+ writeFileSync(+ brainConfigPath(vault),+ "schema_version: 1\nguardrails:\n derived_fact_synthesis: true\n",+ );+}++function seedPremise(slug: string): void {+ writePreference(vault, {+ slug,+ topic: slug,+ principle: `premise ${slug}`,+ created_at: "2026-06-01T00:00:00Z",+ unconfirmed_until: "2026-07-01T00:00:00Z",+ status: "confirmed",+ evidenced_by: [],+ });+}++const ARGS = {+ slug: "derived-1",+ topic: "derived",+ principle: "Therefore C",+ premises: ["pref-a", "pref-b"],+ level: "deduced",+};++describe("brain_derive_fact", () => {+ test("flag off (default): refuses with INVALID_PARAMS, writes nothing", async () => {+ seedPremise("a");+ seedPremise("b");+ await expect(handler(ctx, ARGS)).rejects.toThrow(MCPError);+ });++ test("flag on: commits the derived fact with its provenance level", async () => {+ seedPremise("a");+ seedPremise("b");+ enableDerivation();+ const res = await handler(ctx, ARGS);+ expect(res).toMatchObject({ id: "pref-derived-1", level: "deduced" });+ expect(parsePreference(preferencePath(vault, "derived-1")).provenance).toBe("deduced");+ });++ test("flag on: a missing premise is INVALID_PARAMS", async () => {+ seedPremise("a");+ enableDerivation();+ await expect(handler(ctx, ARGS)).rejects.toThrow(MCPError);+ });++ test("flag on: a 'stated' level is rejected", async () => {+ seedPremise("a");+ seedPremise("b");+ enableDerivation();+ await expect(handler(ctx, { ...ARGS, level: "stated" })).rejects.toThrow(MCPError);+ });+});diff --git a/tests/mcp/ingest-tool.test.ts b/tests/mcp/ingest-tool.test.tsnew file mode 100644index 00000000..7b123d36--- /dev/null+++ b/tests/mcp/ingest-tool.test.ts@@ -0,0 +1,79 @@+/**+ * MCP integration test for `brain_ingest_source` (Knowledge Provenance suite).+ * The agent supplies the extraction + summary; OSB writes entity pages and a+ * per-source summary page. Handler exercised directly with a minimal context.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { listEntities } from "../../src/core/brain/entities/registry.ts";+import { INGEST_TOOLS } from "../../src/mcp/brain/ingest-tools.ts";+import { MCPError } from "../../src/mcp/protocol.ts";+import type { ServerContext } from "../../src/mcp/tools.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-ingest-tool-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-ingest-tool-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const handler = INGEST_TOOLS[0]!.handler;++describe("brain_ingest_source", () => {+ test("writes entity pages and a summary page, returns its vault path", async () => {+ const res = await handler(ctx, {+ source_path: "Articles/eth.md",+ summary: "Ethereum scaling overview.",+ entities: [+ { category: "concept", name: "Rollups" },+ { category: "concept", name: "Data Availability" },+ ],+ relations: [{ from: "Rollups", relation: "related", to: "Data Availability" }],+ });+ expect(res).toMatchObject({ created: true, summary_path: expect.any(String) });+ expect(listEntities(vault, { category: "concept" })).toHaveLength(2);+ // Summary page content is asserted in the core ingest test; here we read+ // the single summary file the ingest produced and confirm the backlink.+ const sourcesDir = join(vault, "Brain", "sources");+ const summaryFiles = readdirSync(sourcesDir).filter((n) => n.endsWith(".md"));+ expect(summaryFiles).toHaveLength(1);+ const md = readFileSync(join(sourcesDir, summaryFiles[0]!), "utf8");+ expect(md).toContain("[[Articles/eth.md]]");+ expect(md).toContain("Ethereum scaling overview.");+ });++ test("a malformed extraction is rejected with INVALID_PARAMS and writes nothing", async () => {+ await expect(+ handler(ctx, {+ source_path: "Articles/eth.md",+ summary: "x",+ entities: [{ category: "concept", name: "A" }],+ relations: [{ from: "A", relation: "causes", to: "A" }],+ }),+ ).rejects.toThrow(MCPError);+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("missing required source_path is rejected", async () => {+ await expect(+ handler(ctx, { summary: "x", entities: [{ category: "concept", name: "A" }] }),+ ).rejects.toThrow(MCPError);+ });+});diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.tsindex a586e897..aa56fbb9 100644--- a/tests/mcp/mcp.test.ts+++ b/tests/mcp/mcp.test.ts@@ -267,6 +267,11 @@ describe("tool listing", () => {"brain_tune",// Agent Write Contract Suite: provider-agnostic write sessions."brain_write_session",+ // Knowledge Provenance Suite (v1.7.0).+ "brain_intake_entities",+ "brain_ingest_source",+ "brain_research_report",+ "brain_derive_fact",].toSorted(),);// Explicit grep: legacy writable tools are no longer advertised.@@ -526,7 +531,9 @@ describe("stdio loop", () => {// + brain_hygiene / brain_anticipatory_context// (continuity-hygiene-freshness suite, v1.3.0) = 71.// + brain_eval (Search & Recall Quality Suite) = 72.- expect(list.result.tools.length).toBe(72);+ // + brain_intake_entities / brain_ingest_source / brain_research_report+ // / brain_derive_fact (Knowledge Provenance Suite, v1.7.0) = 76.+ expect(list.result.tools.length).toBe(76);});test("returns parse error for invalid JSON", async () => {diff --git a/tests/mcp/ner-tool.test.ts b/tests/mcp/ner-tool.test.tsnew file mode 100644index 00000000..523b4e80--- /dev/null+++ b/tests/mcp/ner-tool.test.ts@@ -0,0 +1,100 @@+/**+ * MCP integration tests for `brain_intake_entities` (model-based NER intake,+ * Knowledge Provenance suite). The calling agent owns the recognition; the+ * tool validates the typed payload and commits it through the shared+ * extraction-intake primitive. OSB never runs a model here.+ *+ * The handler is exercised directly with a minimal ServerContext - the arg+ * validation and the INVALID_PARAMS translation are the surface under test.+ */++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 { getEntity, listEntities } from "../../src/core/brain/entities/registry.ts";+import { NER_TOOLS } from "../../src/mcp/brain/ner-tools.ts";+import { MCPError } from "../../src/mcp/protocol.ts";+import type { ServerContext } from "../../src/mcp/tools.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-ner-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-ner-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const handler = NER_TOOLS[0]!.handler;++describe("brain_intake_entities", () => {+ test("intakes agent-supplied entities into the registry", async () => {+ const res = await handler(ctx, {+ entities: [+ { category: "concept", name: "Layer 2s" },+ { category: "people", name: "Vitalik", aliases: ["V."] },+ ],+ });+ expect(res).toEqual({+ entities_created: [expect.any(String), expect.any(String)],+ entities_updated: [],+ relations_applied: 0,+ });+ expect(listEntities(vault)).toHaveLength(2);+ expect(getEntity(vault, { category: "concept", query: "Layer 2s" })?.name).toBe("Layer 2s");+ });++ test("applies typed relations between extracted entities", async () => {+ const res = await handler(ctx, {+ entities: [+ { category: "concept", name: "Restaking" },+ { category: "concept", name: "Validators" },+ ],+ relations: [{ from: "Restaking", relation: "related", to: "Validators" }],+ });+ expect(res).toMatchObject({ relations_applied: 1 });+ const restaking = getEntity(vault, { category: "concept", query: "Restaking" });+ expect(restaking?.relations.some((r) => r.relation === "related")).toBe(true);+ });++ test("cites the source wikilink in a newly created entity body", async () => {+ await handler(ctx, {+ entities: [{ category: "concept", name: "Sharding" }],+ source: "[[Articles/eth-roadmap.md]]",+ });+ const sharding = getEntity(vault, { category: "concept", query: "Sharding" });+ expect(sharding?.body).toContain("## Sources");+ expect(sharding?.body).toContain("[[Articles/eth-roadmap.md]]");+ });++ test("rejects an empty entities array with INVALID_PARAMS and writes nothing", async () => {+ await expect(handler(ctx, { entities: [] })).rejects.toThrow(MCPError);+ expect(listEntities(vault)).toHaveLength(0);+ });++ test("translates an unknown relation into INVALID_PARAMS with no partial write", async () => {+ await expect(+ handler(ctx, {+ entities: [+ { category: "concept", name: "A" },+ { category: "concept", name: "B" },+ ],+ relations: [{ from: "A", relation: "causes", to: "B" }],+ }),+ ).rejects.toThrow(MCPError);+ expect(listEntities(vault)).toHaveLength(0);+ });+});diff --git a/tests/mcp/removed-tools.test.ts b/tests/mcp/removed-tools.test.tsindex f4c8fe59..88e97552 100644--- a/tests/mcp/removed-tools.test.ts+++ b/tests/mcp/removed-tools.test.ts@@ -138,5 +138,5 @@ test("the shadow surface is gone: no hidden tools, removed names unlisted", asynmethod: "tools/list",params: {},})) as { result: { tools: Array<{ name: string }> } };- expect(list.result.tools.length).toBe(72);+ expect(list.result.tools.length).toBe(76);});diff --git a/tests/mcp/research-tool.test.ts b/tests/mcp/research-tool.test.tsnew file mode 100644index 00000000..a7d6b3d7--- /dev/null+++ b/tests/mcp/research-tool.test.ts@@ -0,0 +1,67 @@+/**+ * MCP integration test for `brain_research_report` (Knowledge Provenance+ * suite). The agent supplies title + consulted sources + cited findings; OSB+ * validates the citation contract and writes a dated report page.+ */++import { afterEach, beforeEach, describe, expect, test } from "bun:test";+import { mkdtempSync, rmSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++import { bootstrapBrain } from "../../src/core/brain/init.ts";+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";+import { RESEARCH_TOOLS } from "../../src/mcp/brain/research-tools.ts";+import { MCPError } from "../../src/mcp/protocol.ts";+import type { ServerContext } from "../../src/mcp/tools.ts";++let vault: string;+let configHome: string;+let ctx: ServerContext;++beforeEach(() => {+ vault = mkdtempSync(join(tmpdir(), "o2b-research-tool-vault-"));+ configHome = mkdtempSync(join(tmpdir(), "o2b-research-tool-cfg-"));+ const configPath = join(configHome, "config.yaml");+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);+ bootstrapBrain(vault, { configPath });+ ctx = { vault, configPath, repoRoot: null };+});++afterEach(() => {+ rmSync(vault, { recursive: true, force: true });+ rmSync(configHome, { recursive: true, force: true });+});++const handler = RESEARCH_TOOLS[0]!.handler;++describe("brain_research_report", () => {+ test("writes a cited report and returns its path and finding count", async () => {+ const res = await handler(ctx, {+ title: "Survey",+ sources: ["Articles/a.md", "Articles/b.md"],+ findings: [{ statement: "A point", sources: ["Articles/a.md"] }],+ });+ expect(res).toMatchObject({ created: true, finding_count: 1, report_path: expect.any(String) });+ });++ test("rejects an uncited finding with INVALID_PARAMS", async () => {+ await expect(+ handler(ctx, {+ title: "Survey",+ sources: ["Articles/a.md"],+ findings: [{ statement: "no citation", sources: [] }],+ }),+ ).rejects.toThrow(MCPError);+ });++ test("rejects an empty sources list", async () => {+ await expect(+ handler(ctx, {+ title: "Survey",+ sources: [],+ findings: [{ statement: "x", sources: ["Articles/a.md"] }],+ }),+ ).rejects.toThrow(MCPError);+ });+});