Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: memory write-path integrity and store safety wave (v1.32.0) (#139)

Sol Aitken9a649dd6f741
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 91b1c239..c7984059 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.31.0",
+ "version": "1.32.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index e80d68e3..1fb6cc98 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.31.0",
+ "version": "1.32.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7dcdf7ae..881c13eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,29 @@ 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.32.0] - 2026-07-18
+
+A memory write-path integrity and store safety wave: eleven units across four subsystems that make every durable write choke point validate its input, every destructive vault operation snapshot first, and every embeddings failure surface as a typed, actionable outcome. All gates are deterministic (the kernel still calls no LLM), every rejection is a typed error or a logged, visible skip, and no new dependency is added.
+
+### Added
+
+- **Vector validity gate.** A new `EMBEDDING_INVALID_VECTOR` error rejects non-finite (NaN/Infinity) and all-zero vectors at the store choke points (`vecUpsert`, `semanticTopK`) and in unit normalisation, so a broken embedder can no longer poison cosine distances silently. Previously only the dimension was checked and a NaN vector inserted cleanly.
+- **e5 instruction prefixes at index and query time.** Instruction-tuned embedders get the prompts they require: the embed path now distinguishes `query` from `passage` inputs, the multilingual-e5 preset carries `"query: "`/`"passage: "` defaults, and `embedding_prefix_query`/`embedding_prefix_passage` config keys (with env twins) override them; an explicit empty string disables. The active prefix pair is persisted in index meta, and changing it surfaces the same reindex-required path as a model change, so prefixed queries are never compared against unprefixed stored vectors.
+- **Embeddings quota classification.** HTTP 402, and 429 responses carrying provider quota tokens (for example `insufficient_quota`), now classify as a dedicated non-retriable `EMBEDDING_QUOTA_EXHAUSTED` outcome with an actionable message (quota or billing exhausted, semantic search degraded, check provider billing) instead of folding into a generic HTTP failure with blind retries. The classifier reads structured status fields on the error, not message strings.
+- **Retry-After honoring and graceful semantic degrade.** Rate-limit and transient retries honor the provider's `Retry-After` header (bounded by a 30-second cap); quota outcomes fail fast with zero retries; implicit semantic search degrades to the lexical lane with a warning that names the failure category, while explicit `--semantic` requests keep throwing the typed error rather than silently falling back.
+- **Snapshot-before-destructive-write gate.** A shared `withDestructiveSnapshot` wrapper over the existing tar+zst snapshot engine now fronts `o2b brain forget-source --confirm` (previously an unrecoverable bulk delete) and the new entity prune. The snapshot is taken before any deletion, the run id and archive path are reported as the recovery point, and dry runs take no snapshot.
+- **Entity label quality gate and prune.** `sanitizeEntityLabel` strips surrounding Markdown decoration and punctuation before normalization at every label-intake boundary, and a structural validator (no letter or digit in any script, empty after stripping, over-length, or on the operator-supplied `entities.label_denylist`) rejects junk labels: a typed error at creation, a logged skip at anchoring. `o2b brain entity prune` lists malformed historical nodes (dry-run default) and on `--confirm` removes them and their edges behind the snapshot gate; a new `entity-label-malformed` doctor lint surfaces candidates. Identity keys for all currently-valid labels are byte-stable.
+- **Deterministic durability gate for extracted facts.** A structural classifier (temp paths, progress counters, run-id and timestamp shapes, measurement-token dominance, exit-status shapes; extendable via `durability.denylist` regexes) rejects transient operational content before it persists as durable memory. Rejections are counted and logged as `durability-skip` events, never dropped silently; operator feedback writes are not gated. The classifier ships zero built-in natural-language word lists.
+- **Opt-in write-approval queue.** With `write_approval.enabled: true`, extracted signals stage into `Brain/pending/` instead of landing directly in the inbox; `o2b brain pending list | apply <id> | reject <id> --reason <text>` reviews the queue. Apply moves the unchanged document (anchors and dedup hash preserved) into the inbox; reject moves it to `Brain/retired/` with the reason. Default off preserves the direct-write behavior byte for byte.
+- **Write-time conflict advisory.** Recording feedback whose principle closely resembles a confirmed same-scope preference now returns an advisory naming the conflicting preference id and similarity evidence, in both the `brain_feedback` MCP response and the CLI output, and logs a `write-conflict-advisory` event. The write always proceeds; the advisory tightens the feedback loop that previously waited for the next health pass.
+- **Signal retire lifecycle.** `o2b brain signal retire <id> --reason <text> [--superseded-by <id>]` moves an inbox signal to `Brain/retired/` with retire frontmatter (`_status`, `retired_at`, `retired_reason`, optional `superseded_by`, old-id alias), mirroring the preference retire conventions, so an outdated extracted fact can be superseded without deleting its history. Retired signals leave the dream-pass intake but stay queryable.
+- **Store hardening.** A `harden-permissions` auto-safe remediation step (idempotent, step-capped, dry-run first) tightens existing `Brain/` files to owner-only modes; a `symlink-escape` doctor lint reports vault-internal symlinks resolving outside the vault root.
+
+### Changed
+
+- **MCP responses no longer expose absolute host paths by default.** The `vault_path` fields returned by the core MCP tools now carry a stable opaque reference (`vault://<hash>`) instead of the raw filesystem path, because tool responses land in model context. Set `expose_host_paths: true` (or `OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS=true`) to restore the raw value.
+- **Zero-norm and non-finite vectors now throw during normalisation.** `unitNormaliseInPlace` previously returned an all-zero vector unchanged on zero norm and propagated NaN silently; both cases now raise the typed `EMBEDDING_INVALID_VECTOR` error, because a silent all-zero embedding is a misleading no-op.
+
## [1.31.0] - 2026-07-17
A today-operator-surface release: one read-only dashboard answering "what matters right now", a chronologically merged activity timeline, prose-native open loops, and a guarded write-back that turns prose markers into schema-validated frontmatter mutations. Every read surface is live-derived on demand and never stored; the single write path is opt-in, deterministic, and audited. No new dependency; the kernel still calls no LLM.
@@ -6485,6 +6508,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.32.0]: https://github.com/itechmeat/open-second-brain/compare/v1.31.0...v1.32.0
[1.31.0]: https://github.com/itechmeat/open-second-brain/compare/v1.30.1...v1.31.0
[1.30.1]: https://github.com/itechmeat/open-second-brain/compare/v1.30.0...v1.30.1
[1.30.0]: https://github.com/itechmeat/open-second-brain/compare/v1.29.0...v1.30.0
diff --git a/README.md b/README.md
index c90b10e6..54bd4094 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
## What is new
-Open Second Brain 1.26.1 is an upstream-alignment guard release. Two regression suites now pin the Hermes-facing surface against landed upstream Hermes changes: the memory-provider tool schemas are proven flat and named so the core normalize/validate-before-wrap step never disables the toolset on a strict provider, and the in-place compaction lifecycle is shown to flush each boundary exactly once under one stable session id. No runtime behavior changes, no source edits; the kernel still calls no LLM.
+Open Second Brain 1.32.0 is a memory write-path integrity and store safety release. Every durable write choke point now validates its input: embedding vectors are rejected before they can poison the semantic index, entity labels are stripped of Markdown decoration and structurally validated before graph persistence, and extracted facts pass a deterministic durability gate (with an optional operator write-approval queue) before landing in the brain. Destructive vault operations (`forget-source`, entity prune) take a snapshot first and report the recovery point. Embeddings quota exhaustion is now a distinct, actionable outcome with Retry-After-aware backoff, e5-family models get their required instruction prefixes, and MCP responses carry opaque store references instead of absolute host paths. The kernel still calls no LLM.
## Why
@@ -108,7 +108,8 @@ That is the day-to-day picture. The full capability surface, every CLI verb, and
- Plain Markdown on your filesystem. No daemon, no background writes. The MCP server is a stdio subprocess that exits with the parent runtime. An optional HTTP transport (`o2b mcp --transport http`) is off by default and safe by design: it binds loopback (`127.0.0.1`), enforces a Host/Origin DNS-rebinding guard on every request, and exposes an unauthenticated `GET /health` liveness probe. A bearer token (`--api-key`) is optional on loopback and mandatory when binding a non-loopback host - the server refuses to expose an unauthenticated endpoint on the network.
- Your vault is the only source of truth - no hidden state, no cloud copy.
-- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`.
+- Brain mutations (`dream`, `merge`, `upgrade`) take a pre-run snapshot with a SHA-256 sidecar; `o2b brain rollback` aborts on drift unless `--force-rollback`. Destructive cleanups (`forget-source --confirm`, `entity prune --confirm`) run behind the same snapshot gate and report their recovery point; dry runs take no snapshot.
+- Store hardening: `o2b brain doctor --remediate` can tighten existing `Brain/` files to owner-only permissions (dry-run first, idempotent), the doctor flags vault-internal symlinks that resolve outside the vault, and MCP responses carry an opaque `vault://` store reference instead of the absolute host path unless `expose_host_paths: true` is set.
- Secrets are not supposed to live in the vault. Daily logs and config exports run through a best-effort redactor, `$secret:NAME` references resolve from the local environment and are never stored, and Brain redaction strips `<private>...</private>` regions before storage.
- Automatically surfaced Brain context passes through a deterministic prompt-injection guard; filtered output returns a placeholder with a reason code and the source Markdown is never rewritten. Opt into `untrusted_source_delimiting` for language-agnostic structural containment instead: an untrusted span is wrapped in a provenance-carrying `<untrusted_source path sha256>` delimiter and neutralized by structure (invisible/control characters, delimiter breakouts) rather than a per-language word list, losslessly and identically for every language.
- Context receipts and recall telemetry are opt-in and store redacted metadata, hashes, and counters rather than raw prompt text.
diff --git a/docs/brainstorm/memory-write-path-integrity/cli-output/claude.md b/docs/brainstorm/memory-write-path-integrity/cli-output/claude.md
new file mode 100644
index 00000000..9c290ae6
--- /dev/null
+++ b/docs/brainstorm/memory-write-path-integrity/cli-output/claude.md
@@ -0,0 +1,39 @@
+### Variant 1: Unified WriteGate framework
+
+- **Approach**: Build one cross-cutting gate framework (`src/core/gates/`) with a generic `Gate<T>` interface, a composable `GatePipeline`, and a single typed `WriteRejection` error hierarchy. All 11 units are expressed as gate stages plugged into this pipeline: entity quality, durability classification, conflict advisory, approval staging, vector validation, snapshot-before-destructive, quota classification. Every persist path (vault writes, `vecUpsert`, `deleteBySource`) is refactored to run through the pipeline.
+- **Trade-offs**:
+ - Pro: maximally DRY; one place to reason about "what can reject a write"; uniform rejection logging and doctor visibility for free.
+ - Pro: a single error taxonomy makes CLI/MCP surfacing consistent across all units.
+ - Con: the units span three genuinely different subsystems (Markdown vault writes, the sqlite-vec store, an HTTP embeddings client) with different payload types and failure semantics; a shared `Gate<T>` interface is speculative generality that mostly holds `unknown`.
+ - Con: the framework itself becomes a serialization point - every unit's atomic commit depends on it, so a design flaw discovered at unit 7 forces rework across the whole wave.
+ - Con: units t_3beb374c (e5 prefixes), t_66c12a67 (fact retire), and t_29a63073 (perms migration) are not gates at all and get shoehorned in or left inconsistent.
+- **Complexity**: large
+- **Risk**: high
+
+### Variant 2: Per-unit isolated changes
+
+- **Approach**: Each unit lands independently at its natural existing choke point with no new shared modules: extend `normalizeEntityName` in place, add checks inside `vecUpsert`, add a durability check inside the write path, patch `classifyError` twice (once per embeddings unit), wrap `deleteBySource` with a direct `createSnapshot` call, and so on. Error codes are added ad hoc per subsystem as each unit needs them.
+- **Trade-offs**:
+ - Pro: trivially atomic commits with no ordering constraints; any unit can be dropped or reverted without touching the others.
+ - Pro: smallest possible diff per unit; matches the "improvement, not net-new" scoping of several units.
+ - Con: the brain write path ends up with four uncoordinated pre-persist checks (capture-boundary, pinned budget, durability, approval queue, conflict advisory) with inconsistent rejection surfacing - exactly the "scattered per-call-site checks" the project constraints forbid.
+ - Con: t_8880a68d and t_144b680a both rework `classifyError`; done independently they conflict or duplicate Retry-After/quota parsing.
+ - Con: rejection logging conventions diverge per unit, making doctor/hygiene visibility (required by the no-silent-drop constraint) inconsistent.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Cluster-scoped kernels, per-unit atomic commits
+
+- **Approach**: Group the 11 units into four subsystem clusters and introduce a small shared kernel only where units provably share a choke point, then land each unit as an atomic commit on top of its kernel. Cluster A (brain write path: durability gate, approval queue, conflict advisory, entity reject, fact retire) gets a light `src/core/brain/gates/` chain with one typed `WriteRejection` result and one logged-skip convention that also fronts the existing capture-boundary and pinned budget gates; Cluster B (vec store: NaN/zero validation, e5 prefixes) gets a `validateVector` util at `vecUpsert` plus preset-aware prefix config in `presets.ts`; Cluster C (embeddings client: quota classification, Retry-After/degrade) gets one refactor of `classifyError` into a richer `{category, retriable, retryAfterMs}` classification with new `EMBEDDING_QUOTA_*`/rate-limit SearchError codes, consumed by both units in sequence; Cluster D (store safety: snapshot gate, hardening/prune) gets a `withSnapshot(label, op)` wrapper over the existing `snapshot.ts` engine, reused by `deleteBySource`, the entity prune, and future destructive ops, with the perms migration and symlink guard landing as doctor/maintenance passes.
+- **Trade-offs**:
+ - Pro: DRY exactly where coupling is real (the two embeddings units, the multiple brain gates, the two-plus snapshot consumers) without inventing a cross-subsystem abstraction.
+ - Pro: preserves per-unit atomic commits - each kernel is itself a small commit, and units within a cluster stack on it while clusters remain mutually independent, so partial shipping stays possible.
+ - Pro: error-type design stays subsystem-native (SearchError codes for search/embeddings, `WriteRejection` for brain writes), honoring existing conventions instead of unifying them artificially.
+ - Con: requires deciding cluster boundaries and kernel interfaces up front, and sequencing within clusters (classifier before handling, gate chain before the gates that plug into it).
+ - Con: two error vocabularies coexist; a reviewer must understand which subsystem a rejection belongs to.
+- **Complexity**: medium
+- **Risk**: low
+
+### Recommended: Variant 3
+
+**Rationale**: The wave's units cluster naturally along OSB's existing module seams (brain vault, search store, embeddings client, snapshot engine), and Variant 3 puts shared abstractions only at choke points that two or more units actually share - satisfying the repo's "shared choke points over scattered checks" and typed-error constraints without Variant 1's speculative cross-subsystem framework or Variant 2's duplicated `classifyError` rework and uncoordinated gate sprawl. It also keeps every unit an independently revertable atomic commit on one branch, which is exactly what an 11-unit single-release wave needs when any one unit could stall in review.
diff --git a/docs/brainstorm/memory-write-path-integrity/cli-output/prompt.md b/docs/brainstorm/memory-write-path-integrity/cli-output/prompt.md
new file mode 100644
index 00000000..034480da
--- /dev/null
+++ b/docs/brainstorm/memory-write-path-integrity/cli-output/prompt.md
@@ -0,0 +1,277 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+This is a MULTI-UNIT release wave for the project Open Second Brain: 11 related kanban units under one theme - "memory write-path integrity and store safety". Each unit ships in the same release on one feature branch as an atomic commit. Your variants must address HOW TO ARCHITECT THE WAVE AS A WHOLE (shared abstractions vs per-unit isolated changes, gate composition, error-type design, module layout), not re-litigate whether the units are worth doing.
+
+## Unit t_657b365e (board priority 4): [upstream:signetai] Strip Markdown from entity labels and reject scaffolding names before graph persistence
+
+**Source**: https://github.com/Signet-AI/signetai/releases/tag/v0.147.9
+**Repo**: Signet-AI/signetai (183★)
+**Released**: v0.147.9 (2026-07-11)
+
+## What
+Extend entity-name normalization to strip surrounding Markdown (`**`, `__`, `##`) and punctuation before quality checks, and reject generic scaffolding labels / discourse markers before graph persistence; add an operator-safe prune that removes historical malformed entity nodes without leaving orphaned graph rows. Mirrors Signet's "rejected markdown-polluted entity labels" (#914).
+
+## Why useful for OSB
+OSB already normalizes entity names via `normalizeEntityName` but only does NFC + whitespace collapse + lowercase — it does not strip Markdown/punctuation and does not reject junk/scaffolding labels. Downstream consumers (atomic-facts, fact-extract) inherit the limitation, so markdown-polluted or scaffolding entity names can reach graph persistence and fragment entity matching (e.g. `**Foo**` vs `foo` become different entities). Stronger normalization + a junk-label reject + a safe prune improves entity-graph quality and recall consistency.
+
+## Status in OSB
+- **Verdict**: present_weaker
+- **Codegraph hints**: `src/core/brain/entities/canonical.ts:12-13` — `normalizeEntityName(raw)` = `raw.normalize("NFC").trim().replace(/\s+/g," ").toLowerCase()` only; NO Markdown/punctuation stripping, NO scaffolding/discourse rejection; `src/core/brain/atomic-facts.ts:116-120` and `src/core/brain/fact-extract.ts:206-210` reuse normalizeEntityName for entity matching, inheriting the limitation.
+
+## Notes
+Extend normalizeEntityName (or add a pre-quality-check strip pass) to remove surrounding Markdown emphasis/headings and surrounding punctuation. Maintain a denylist of generic scaffolding labels and discourse markers to reject before persistence. The operator-safe prune should delete malformed historical nodes and their edges transactionally to avoid orphaned graph rows; surface prune candidates via brain_hygiene/brain_doctor. Ensure changes to normalizeEntityName stay backward-compatible with the existing identity-key shape (`<category>:<normalized name>`).
+
+## Unit t_e2b182b6 (board priority 4): [upstream:yantrikdb] NaN/all-zero embedding validation gate before vecUpsert (dimension-only today)
+
+**Source**: https://github.com/yantrikos/yantrikdb/releases/tag/v0.9.3
+**Repo**: yantrikos/yantrikdb (31★)
+**Released**: v0.9.3 (2026-07-14T01:38:07Z)
+
+## What
+yantrikdb added a central contract gate that validates every embedding/scalar with typed `InvalidEmbedding {path,index,reason}` / `InvalidScalar` errors BEFORE any side effect on every entry path, catching external-embedder NaN (e.g. ONNX 0/0) and wrong-dimension vectors that previously panicked.
+
+## Why useful for OSB
+OSB validates embedding dimension before storing (`vecUpsert` throws `EMBEDDING_DIMENSION_MISMATCH`), but nothing checks that vector values are finite or non-zero: `vecToBuffer` writes NaN straight to the vec table and `unitNormaliseInPlace` silently returns an all-zero vector on zero norm. A broken OpenAI-compatible endpoint or a future local ONNX provider emitting NaN would poison that chunk's cosine distance (NaN distances → erratic/absent retrieval) with no error surfaced.
+
+## Status in OSB
+- **Verdict**: present_weaker
+- **Codegraph hints**: dimension gate present (`src/core/search/store.ts:834-840` `vecUpsert`, `src/core/search/indexer.ts:611`, `src/core/search/embeddings/openai-compat.ts:332`); NaN/finite + all-zero gate absent (`src/core/search/store.ts:331-334` `vecToBuffer` does `Float32Array.from` with no validation; `src/core/search/embeddings/http-util.ts:48-55` `unitNormaliseInPlace` propagates NaN and returns an all-zero vector on zero norm with no error).
+
+## Notes
+Improvement, not net-new: add a finite/non-zero check at the single choke point `vecUpsert` (and optionally at provider-parse time in `unitNormaliseInPlace` / `openai-compat.ts:338`) so a bad embedder output is rejected with a typed error before it reaches the index, mirroring yantrikdb's pre-write contract gate. Scope is narrow — OSB already funnels all vector writes through `vecUpsert`.
+
+## Unit t_375e98fd (board priority 3): [upstream:signetai] Deterministic durability gate rejecting transient operational content before persist
+
+**Source**: https://github.com/Signet-AI/signetai/releases/tag/v0.147.9
+**Repo**: Signet-AI/signetai (183★)
+**Released**: v0.147.9 (2026-07-11)
+
+## What
+Add a deterministic pre-persist durability gate that classifies and rejects transient operational content (queue counts, in-progress state, temporary paths, run/test status, self-diagnostics) before it is written as durable memory. Mirrors Signet's durability gate (#917) that closes the gap where high-confidence-but-ephemeral content passed all existing gates.
+
+## Why useful for OSB
+OSB's existing content gates operate on different axes: capture-boundary validates capture-pattern VALIDITY (not content semantics), and pinned.ts rejects over-budget content by SIZE. Neither inspects whether the content is transient operational noise, so ephemeral content (status counts, in-progress markers, self-diagnostics) can pass every current gate and land as durable memory, polluting recall. A content-semantics durability gate keeps durable memory free of operational noise.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: `src/core/brain/capture-boundary.ts:14-69` — skips invalid capture PATTERNS at compile time (doctor surfaces them); a pattern-validity gate, not content semantics; `src/core/brain/pinned.ts:86` — rejects over-budget pinned content by SIZE (structured signal) before write; a budget gate, not a transient-noise gate; no deterministic gate that rejects transient operational content before durable persistence was found.
+
+## Notes
+The classifier must be deterministic (no LLM) to match the upstream "deterministic durability gate" guarantee and avoid adding inference cost to the hot ingest path. Define the transient-content vocabulary (queue counts, in-progress state, temporary paths, run/test status, self-diagnostics) explicitly. Rejected content can be logged for doctor visibility rather than silently dropped. Coordinate with the existing capture-boundary + pinned budget gates so the three form one coherent pre-persist filter chain.
+
+## Unit t_e540b093 (board priority 3): [upstream:mnemosyne] Write-approval gate — stage extracted memory writes to a pending queue and apply only after review
+
+**Source**: https://github.com/AxDSan/mnemosyne/releases/tag/v3.14.0
+**Repo**: AxDSan/mnemosyne (629★)
+**Released**: v3.14.0 (2026-07-17T20:42:11Z)
+
+## What
+Add an opt-in write-approval mode that stages memory writes (e.g. extracted-fact signals) into a pending queue instead of committing them straight to the live brain, plus an apply action that replays only human-approved records into the canonical store.
+
+## Why useful for OSB
+OSB currently writes facts as `source_type: extracted` signals directly with no review checkpoint, so a noisy or wrong extraction lands in the brain immediately. A pending/approve gate gives the operator a chance to vet auto-extracted memory before it becomes queryable, reducing pollution of the canonical store.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: No write-approval/pending-memory gate exists — `fact-extract.ts:217` writes extracted signals directly; grep `write.approval|pending/memory|staging.*write|apply.pending` = 0 real hits (only unrelated DB-build staging at `search/store.ts:255`, `indexer.ts:642`, and dream staging).
+
+## Notes
+Scope as opt-in (default off) so existing direct-write flow is unchanged. Design the apply step to preserve canonical-entity anchoring done at extraction time.
+
+## Unit t_f79b4fe0 (board priority 3): [upstream:aipass] Synchronous write-time conflict advisory when an incoming fact contradicts an existing belief (supersedes links already present)
+
+**Source**: https://github.com/AIOSAI/AIPass/releases/tag/v2.7.2
+**Repo**: AIOSAI/AIPass (214★)
+**Released**: v2.7.2 (2026-07-17T06:45:33Z)
+
+## What
+Decision curation that maintains supersedes links plus emits a conflict advisory *at write time* when an incoming fact contradicts an existing one. OSB already has the curation + supersedes half comparably; the gap is the synchronous, ingress-time advisory (OSB detects/resolves conflicts in a later health/dream pass, not at the moment of write).
+
+## Why useful for OSB
+Warning at write ingress catches a contradiction while the operator/agent is still in context to reconcile it, instead of deferring to the next hygiene pass. It tightens the feedback loop on belief conflicts without changing the existing detection logic.
+
+## Status in OSB
+- **Verdict**: present_weaker
+- **Codegraph hints**: `health/contradiction.ts`, `reconcile.ts:70` (detectContradictions), `thesis.ts:452` (support/contradiction over subject-bearing span), `hygiene/resolve-conflicts.ts` (supersede action) — supersedes links + contradiction detection at parity; gap is that these run as a health/dream pass, not synchronously at write ingress.
+
+## Notes
+Scope the task narrowly to the write-time advisory hook (reuse `detectContradictions`/`resolve-conflicts.ts` supersede logic at ingress) — do not rebuild the already-comparable detection/supersedes machinery.
+
+## Unit t_7965b04b (board priority 4): [upstream:obsidian-wiki] Snapshot-before-destructive-write gate covering bulk deletes (deleteBySource)
+
+**Source**: https://github.com/Ar9av/obsidian-wiki/releases/tag/v2026.07.6
+**Repo**: Ar9av/obsidian-wiki (977★)
+**Released**: v2026.07.6 (2026-07-14T16:53:39Z)
+
+## What
+Upstream now takes a git snapshot of the vault (with a hardened snapshot path) before any skill performs a destructive write, so the change is recoverable/rollback-able. It generalizes snapshotting to cover destructive skill writes broadly, not just one operation.
+
+## Why useful for OSB
+OSB already owns the hard part — a full-vault snapshot + rollback engine (tar+zst, retention rotation, restore that preserves `.snapshots/`) — but only three batch paths (`dream`, `upgrade`, `import-claude-memory`) invoke it. Other destructive mutations, notably `deleteBySource`'s bulk `rmSync`, have no pre-write snapshot, so a mistaken bulk delete is unrecoverable despite the machinery existing.
+
+## Status in OSB
+- **Verdict**: present_weaker
+- **Codegraph hints**: `createSnapshot` at src/core/brain/snapshot.ts:175 (tar+zst full-`Brain/` archive → `Brain/.snapshots/<run_id>.tar.zst`), with `restoreSnapshot` rollback + `pruneSnapshots` retention (snapshot.ts:1-33 contract); WIRED INTO ONLY: src/core/brain/dream.ts:383 (pre-run gate), src/core/brain/upgrade.ts:28, src/core/brain/import-claude-memory.ts:80; UNCOVERED destructive path: `deleteBySource` in src/core/brain/source-cleanup.ts (destructive `rmSync`, writes tombstone only, NO snapshot); individual writes use atomicWrite (partial-write safety, not rollback); src/core/brain/git/store.ts + brain_note_history = ingesting/reading external repo git history, not vault snapshotting.
+
+## Notes
+Improvement, not net-new: extend the existing `snapshot.ts` engine into a shared "snapshot-before-destructive-write" gate that fronts other destructive vault operations (start with `deleteBySource`), rather than adopting upstream's git mechanism — OSB's self-contained tar+zst approach is arguably stronger (no requirement that the vault be a git repo, plus built-in retention). Optionally align the snapshot-path hardening idea with `validateRunId`/`snapshotPath` in src/core/brain/paths.ts. Related but distinct from the typed lifecycle-history/revert task: this one is specifically about extending the existing snapshot gate's coverage.
+
+## Unit t_29a63073 (board priority 4): [upstream:contextlattice] Harden local stores — resumable permission migration, in-store symlink guard, opaque store references in outputs
+
+**Source**: https://github.com/sheawinkler/contextlattice/releases/tag/v3.17.3
+**Repo**: sheawinkler/contextlattice (61★)
+**Released**: v3.17.3 (2026-07-13T14:53:23Z)
+
+## What
+Sensitive local stores are locked to owner-only access (restrictive POSIX modes on Unix, ACLs on Windows), applied to *existing* stores via a bounded, resumable migration pass. Symlink targets are constrained to stay inside the store boundary (no escaping to arbitrary host paths). Runtime responses expose opaque store references instead of raw host filesystem paths.
+
+## Why useful for OSB
+OSB is local single-tenant over a Markdown vault, so store hardening is squarely in scope. OSB already writes new files owner-only, but three gaps remain: (1) pre-existing files/stores created before the mode discipline are never re-secured; (2) a symlink inside the vault can point outside it, defeating the owner-only guarantee and enabling path traversal; (3) runtime responses can leak absolute host paths, which is an info-disclosure and portability leak. Closing these matches OSB's existing opaque-id discipline and audit posture.
+
+## Status in OSB
+- **Verdict**: present_weaker
+- **Codegraph hints**: Owner-only modes for *new* writes already present — `src/core/fs-atomic.ts:107` default mode `0o600` (`:153` `0o644`), `src/core/reliability/audit.ts:26` append-only `0o600`, `src/core/doctor.ts:50,70` `chmod u+rwx` checks. Opaque ids exist but only for telemetry — `src/core/config.ts:563,584`. Not found: (a) a bounded resumable migration that re-secures existing stores — reason: no such pass surfaced; (b) a symlink-target-inside-store guard — reason: no traversal check surfaced; (c) opaque store-reference redaction in *runtime response payloads* — reason: opaque-id discipline is telemetry-only, not applied to output paths.
+
+## Notes
+The owner-only-mode sub-feature is at parity for new writes; the create-worthy delta is the three missing pieces. Suggest: (1) a resumable doctor/maintenance migration that chmods existing store files with checkpointing; (2) a realpath containment check rejecting symlinks whose target resolves outside the vault/store root; (3) a path→opaque-reference redactor for MCP/CLI response payloads, reusing the existing opaque-id approach from `config.ts`.
+
+## Unit t_66c12a67 (board priority 3): [upstream:mnemosyne] Retire canonical fact slots (mark superseded, keep historical record queryable) instead of hard-deleting
+
+**Source**: https://github.com/AxDSan/mnemosyne/releases/tag/v3.14.0
+**Repo**: AxDSan/mnemosyne (629★)
+**Released**: v3.14.0 (2026-07-17T20:42:11Z)
+
+## What
+Give facts a retire lifecycle: an operator can mark a canonical fact slot inactive/superseded without deleting it, keeping the historical record queryable — mirroring what OSB already does for preferences but for extracted/canonical facts.
+
+## Why useful for OSB
+OSB has no operator-managed retire path for facts — a stale fact can only be deleted by source, losing history. A retire-not-delete slot lets an outdated fact be superseded while remaining auditable, matching the retire semantics preferences already enjoy.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: Facts are extracted signals anchored to canonical entities (`fact-extract.ts:199`, `:201`, `:217`) with no fact-level CRUD/retire; the retire lifecycle that exists is preferences-only (`pref-audit.ts:16` create/promote/retire/merge, `query.ts:8` active-or-retired). No canonical-fact retire found.
+
+## Notes
+Model the fact retire after the existing preference retire lifecycle rather than inventing new semantics; keep full CRUD scope minimal — the retire/supersede half is the load-bearing part for OSB.
+
+## Unit t_3beb374c (board priority 3): [upstream:mnemosyne] Apply e5 `query:`/`passage:` instruction prefixes at index and query time (configurable)
+
+**Source**: https://github.com/AxDSan/mnemosyne/releases/tag/v3.14.0
+**Repo**: AxDSan/mnemosyne (629★)
+**Released**: v3.14.0 (2026-07-17T20:42:11Z)
+
+## What
+Apply distinct instruction prefixes for queries vs documents when embedding — `query:` at search time and `passage:` at index time — with the prefixes configurable, so instruction-tuned embedders (E5/BGE) get the prompts they require.
+
+## Why useful for OSB
+OSB's embedding preset is multilingual-e5-small, which *requires* separate `query:`/`passage:` prefixes for correct retrieval, yet OSB applies none today. This is a retrieval-correctness fix: adding the prefixes materially improves semantic-search relevance for the model OSB already ships.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: Preset is multilingual-e5-small (`search/embeddings/presets.ts:40-41`); no instruction-prefix handling exists — grep `instruction|query.prompt|queryPrefix` in `embeddings/` = 0 hits.
+
+## Notes
+Reindex is required after adding passage prefixes so stored vectors match the new instruction; make prefixes preset-aware (defaults for e5) and overridable, and ensure query-side prefix is applied consistently at search time. Highest retrieval-quality payoff of the four.
+
+## Unit t_8880a68d (board priority 2): [upstream:mem9] Classify embeddings-provider quota/billing errors (402 / quota-429) distinctly from generic transient failures and surface an actionable message
+
+**Source**: https://github.com/mem9-ai/mem9/pull/383
+**Repo**: mem9-ai/mem9 (1147★)
+**PR**: #383 feat(runtime): define public quota error contract (2026-07-04T14:29:39Z)
+
+## What
+OSB's opt-in embeddings layer should distinguish a quota-exhausted / billing-blocked outcome (HTTP 402) and a quota-shaped 429 from generic transient failures, mapping them to a dedicated error category with an actionable, user-facing message. This is the client-side kernel of the upstream idea — NOT the mem9 server/HTTP contract, which OSB has no surface for.
+
+## Why useful for OSB
+Today a 402 is folded into a blind EMBEDDING_PROVIDER_HTTP failure and every 429 is retried identically, so a user whose embedding billing is exhausted gets a generic error or wasted backoff instead of "embedding quota exhausted — semantic search degraded, check billing." A quota category lets the CLI/agent tell the user why semantic search stopped and skip the pointless retry loop on a hard billing block.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: src/core/search/embeddings/openai-compat.ts:24 (`RETRYABLE_STATUSES = {429,500,502,503,504}` — 402 absent, so it fails fast but with no distinct category; 429 always retried without checking whether it is quota-shaped); src/core/search/embeddings/openai-compat.ts:270-276 (every non-ok status, including 402, collapses into a single `EMBEDDING_PROVIDER_HTTP` SearchError carrying only the status text); src/core/search/embeddings/openai-compat.ts:330-353 (`classifyError` returns only `{retriable, error}` — no quota classifier, no `Retry-After` parsing); SearchError codes in src/core/search/types.ts have no `EMBEDDING_QUOTA_*` member.
+
+## Notes
+Scope is client-side classification only: add a quota SearchError code, treat 402 (and quota-shaped 429 payloads) as a non-retriable quota outcome, optionally honor `Retry-After` for the quota-429 case, and thread an actionable message to the `--semantic` surface / implicit warning path. Do NOT build a mem9-style server contract, OpenAPI schema, or `details.runtimeQuota` HTTP envelope — OSB has no hosted route or API clients. Detecting a "quota-shaped 429" reliably across OpenAI-compatible providers is the main risk (bodies vary); a conservative heuristic plus keeping generic 429 retry behavior as the default is advisable. Orthogonal to t_9b0bb1be (which is about retry COUNT for 429, not error classification).
+
+## Unit t_144b680a (board priority 2): [upstream:mem9] Honor Retry-After and gracefully degrade semantic search on embeddings rate-limit/quota signals
+
+**Source**: https://github.com/mem9-ai/mem9/pull/374
+**Repo**: mem9-ai/mem9 (1147★)
+**PR**: #374 feat: support runtime quota and rate-limit handling in plugins (2026-07-06T07:37:53Z)
+
+## What
+Companion to mem9 #383 (which defined the quota error contract). #374 adds the runtime handling side: the embeddings/plugin runtime observes quota and rate-limit signals and reacts gracefully — honoring Retry-After, backing off on rate-limit distinctly from quota exhaustion, and degrading rather than crashing or retrying blindly.
+
+## Why useful for OSB
+OSB's embeddings client treats 429 identically to 5xx (RETRYABLE_STATUSES = {429,500,502,503,504}) and blind-retries with no Retry-After parsing and no behavioral split between rate-limit and quota exhaustion. Honoring Retry-After and degrading semantic search to lexical fallback when the provider is rate-limited (instead of failing the request) makes optional semantic search resilient to provider throttling.
+
+## Status in OSB
+- **Verdict**: not_in_osb_useful
+- **Codegraph hints**: src/core/search/embeddings/openai-compat.ts:24 (429 pooled with 5xx as blindly-retryable); :270-276 (every non-ok status collapses to a single EMBEDDING_PROVIDER_HTTP); :330-353 (classifyError returns {retriable,error} only — no Retry-After parsing, no rate-limit vs quota behavioral split). No graceful-degradation path for semantic search on throttling.
+
+## Notes
+Distinct from — but coupled with — t_8880a68d (which covers classifying the error category) and orthogonal to t_9b0bb1be (retry count). This task is the reaction/handling layer: Retry-After honoring + rate-limit-vs-quota backoff behavior + graceful degrade of semantic search. Implement on top of t_8880a68d's classification (the classifier should expose Retry-After and the rate-limit/quota distinction that this handling consumes); sequence after or alongside it.
+
+# Project context
+
+Open Second Brain - TypeScript, Bun runtime, local single-tenant CLI (`o2b`) + MCP server over an Obsidian-compatible Markdown vault. SQLite (bun:sqlite) with optional sqlite-vec semantic index. No hosted server, no HTTP API of its own (the only outbound HTTP is the OpenAI-compatible embeddings client).
+Recent commits:
+13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137)
+fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136)
+a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135)
+70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134)
+ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)
+5cd52e70 fix(hermes): resolve o2b when memory provider PATH is tiny (v1.27.1) (#131)
+99adb65f feat: ingestion & import robustness (v1.27.0) (#132)
+fb474acc test(hermes): verify OSB surface against core normalize/validate-before-wrap and in_place compaction (1.26.1) (#129)
+61a9ad66 fix(brain): CodeRabbit review hardening for the unreleased v1.26.0 (#128)
+962c3e0a feat(brain): memory-signal provenance and lifecycle integrity layer (v1.26.0) (#127)
+Related files:
+- src/core/brain/entities/canonical.ts (normalizeEntityName - NFC/trim/collapse/lowercase only)
+- src/core/brain/atomic-facts.ts, src/core/brain/fact-extract.ts (entity matching consumers; fact-extract.ts:217 writes extracted signals directly)
+- src/core/search/store.ts (vecUpsert:834, vecToBuffer:331 - dimension gate only, no finite/non-zero check)
+- src/core/search/embeddings/http-util.ts (unitNormaliseInPlace:48 - returns all-zero on zero norm)
+- src/core/search/embeddings/openai-compat.ts (RETRYABLE_STATUSES {429,500,502,503,504}, classifyError returns {retriable,error} only, no Retry-After parsing, no quota category)
+- src/core/search/embeddings/presets.ts (multilingual-e5-small preset, note mentions query:/passage: prefixes but nothing applies them)
+- src/core/search/types.ts (SearchError codes - no EMBEDDING_QUOTA_*)
+- src/core/brain/snapshot.ts (createSnapshot:175 tar+zst full-Brain archive, restoreSnapshot, pruneSnapshots; wired into dream.ts:383, upgrade.ts:28, import-claude-memory.ts:80 only)
+- src/core/brain/source-cleanup.ts (deleteBySource - bulk rmSync, tombstone only, NO snapshot)
+- src/core/fs-atomic.ts (atomicWrite, default mode 0o600/0o644 for NEW writes only)
+- src/core/brain/capture-boundary.ts (capture-pattern validity gate), src/core/brain/pinned.ts:86 (size budget gate)
+- src/core/brain/pref-audit.ts (preference retire lifecycle: create/promote/retire/merge), src/core/brain/preference.ts:256 (superseded_by)
+- src/core/brain/health/contradiction.ts, src/core/brain/reconcile.ts:70 (detectContradictions), src/core/brain/hygiene/resolve-conflicts.ts (supersede action)
+- src/core/config.ts:563,584 (opaque ids - telemetry only)
+- src/core/doctor.ts (read-only diagnostics), src/core/brain/vitals.ts (orphan_preferences read-only)
+Conventions:
+- Strict TypeScript, no `any`; import cycles are forbidden (v1.30.1 removed all of them; code-ranker gate)
+- Deterministic kernel: the core calls no LLM; LLM-dependent behavior lives behind explicit opt-in surfaces
+- Errors are typed and explicit (SearchError codes, structured lint findings); silent fallbacks are forbidden
+- Frontmatter-first Markdown artifacts in Brain/; every mutation goes through atomicWrite and is logged
+- CLI verbs under src/cli/brain/verbs/, MCP tools under src/mcp/; both are thin adapters over src/core
+- Tests: bun test, colocated *.test.ts; TDD per atomic unit
+- Language-agnostic: no hardcoded natural-language word lists for classification; structural signals, explicit frontmatter fields, corpus frequency, or config-supplied vocabularies only
+Constraints:
+- Do not change existing public API shapes (CLI flags and MCP tool contracts are additive-only)
+- No new external dependencies unless unavoidable
+- No LLM calls in any of these gates - all 11 units must be deterministic
+- Backward compatible: existing vaults must keep working without migration prompts; identity-key shape `<category>:<normalized name>` must remain stable for existing entities
+- Silent no-op fallbacks are forbidden - a rejected write must surface a typed, actionable error or a logged, visible skip
+- SOLID/KISS/DRY: shared choke points preferred over scattered per-call-site checks
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+### Recommended: Variant N
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/memory-write-path-integrity/design.md b/docs/brainstorm/memory-write-path-integrity/design.md
new file mode 100644
index 00000000..fd70acfc
--- /dev/null
+++ b/docs/brainstorm/memory-write-path-integrity/design.md
@@ -0,0 +1,99 @@
+# Memory write-path integrity and store safety - an 11-unit hardening wave
+
+**Status:** draft
+**Author:** claude-dev-agent (via feature-release-playbook)
+**Audience:** implementation
+**Branch:** `feat/memory-write-path-integrity`
+**Consultant:** Claude Code (variants in `variants.md`, raw output in `cli-output/claude.md`)
+
+## Problem statement
+
+Open Second Brain funnels every durable memory mutation through a small set of choke points (`writeSignal`, `vecUpsert`, `deleteBySource`, the embeddings client), but several of those choke points accept input they should reject and several destructive paths lack the safety machinery that already exists elsewhere in the codebase. A malformed entity label fragments the entity graph, a NaN vector poisons cosine distances silently, a bulk `deleteBySource` is unrecoverable despite a full snapshot engine sitting one import away, and an exhausted embeddings quota surfaces as a generic HTTP failure with blind retries. This wave closes those gaps as one coherent release: every unit strengthens the write path or the safety envelope around it, with typed, explicit errors and no silent fallbacks.
+
+## Scope
+
+Eleven kanban units, grouped into four subsystem clusters:
+
+Cluster A - brain write path:
+- **A1** `t_657b365e` (p4) - strip Markdown/punctuation decoration from entity labels, reject structurally-junk labels before graph persistence, snapshot-gated prune of historical malformed entity nodes.
+- **A2** `t_375e98fd` (p3) - deterministic durability gate rejecting transient operational content before an extracted signal is persisted.
+- **A3** `t_e540b093` (p3) - opt-in write-approval queue: stage extracted signal writes to `Brain/pending/`, apply or reject via a new CLI surface.
+- **A4** `t_f79b4fe0` (p3) - synchronous write-time conflict advisory when an incoming signal contradicts a confirmed preference.
+- **A5** `t_66c12a67` (p3) - retire lifecycle for extracted fact signals (mark superseded and move to `Brain/retired/`, keep queryable), modeled on the preference retire lifecycle.
+
+Cluster B - vector store:
+- **B1** `t_e2b182b6` (p4) - finite/non-zero vector validation gate at `vecUpsert` plus a typed error from `unitNormaliseInPlace` on zero-norm or non-finite input.
+- **B2** `t_3beb374c` (p3) - instruction prefixes (`query:` / `passage:`) applied at query and index time, preset-aware defaults for e5-family models, configurable.
+
+Cluster C - embeddings client resilience:
+- **C1** `t_8880a68d` (p2) - classify quota/billing outcomes (HTTP 402, quota-shaped 429) distinctly from generic transient failures, with a dedicated error code and actionable message.
+- **C2** `t_144b680a` (p2) - honor `Retry-After`, split rate-limit backoff from quota fail-fast, degrade implicit semantic search gracefully with an actionable warning.
+
+Cluster D - store safety:
+- **D1** `t_7965b04b` (p4) - shared snapshot-before-destructive-write gate over the existing `snapshot.ts` engine, wired into `deleteBySource` (and reused by the A1 entity prune).
+- **D2** `t_29a63073` (p4) - store hardening: bounded idempotent permission migration for existing `Brain/` files, a doctor lint for symlinks escaping the vault, opaque store references instead of absolute host paths in MCP responses.
+
+## Out of scope
+
+- No LLM-backed classification anywhere in this wave; every gate is deterministic.
+- No mem9-style server quota contract, OpenAPI schema, or HTTP envelope (the project has no hosted API surface).
+- No rebuild of the existing conflict-resolution supersede machinery (`hygiene/resolve-conflicts.ts`); A4 reuses detection, it does not replace resolution.
+- No full CRUD for facts; A5 ships the retire/supersede half only.
+- No git-based snapshot mechanism; D1 extends the existing tar+zst engine.
+- No temporal half-open interval model (`valid_from`/`valid_to` at instant precision) - the atomic temporal fact-replacement task (`t_3ba9c404`) stays on the board.
+- No changes to existing public CLI flag or MCP tool contracts beyond additive fields, new verbs, and new configuration keys.
+
+## Chosen approach
+
+Variant 3 from the consultant run: cluster-scoped kernels with per-unit atomic commits. A shared abstraction is introduced only where two or more units provably share a choke point:
+
+- Cluster A gets a light pre-persist gate seam inside the extracted-signal path (`routeExtractedFacts` -> durability gate -> approval staging -> `writeSignal`), one logged-skip convention, and reuses the existing retire/audit patterns for A5.
+- Cluster B gets one vector-validity kernel used by both the store write path and the provider normalisation path, and one `kind`-aware embed choke point for prefixes.
+- Cluster C gets a single richer classification result (`category`, `retriable`, `retryAfterMs`) consumed by both C1 and C2, avoiding a double rework of `classifyError`.
+- Cluster D gets one `withDestructiveSnapshot` wrapper reused by `deleteBySource` and the A1 prune, and reuses the existing remediation plan/apply machinery for the permission migration.
+
+Clusters stay mutually independent so any unit remains an independently revertable atomic commit; error vocabularies stay subsystem-native (`SearchError` codes for search/embeddings, typed brain-side errors and logged skips for vault writes).
+
+## Design decisions
+
+- **A1 keeps `normalizeEntityName` byte-stable and adds a separate decoration-stripping quality pass.** The identity-key shape `<category>:<normalized name>` (built by `entityIdentityKey`, `src/core/brain/entities/canonical.ts`) must not change for existing entities, so Markdown/punctuation stripping (`**Foo**` -> `Foo`, trailing `:`/`.` etc.) runs as a new exported `sanitizeEntityLabel(raw)` applied BEFORE `normalizeEntityName` at label-intake boundaries (entity creation, fact-extract anchoring, atomic-facts anchoring). Junk rejection is structural only: labels that are empty after stripping, contain no letter or digit in any script (Unicode property classes, not ASCII), collapse to pure punctuation/digits, or exceed a length bound are rejected with a typed error at creation and skipped-with-log at anchoring time. There is NO built-in natural-language denylist; an optional `entities.label_denylist` config key accepts operator-supplied exact labels (compared post-normalization). The prune walks `Brain/entities/`, re-runs the same validator, and removes failing nodes plus their edges behind the D1 snapshot gate, surfaced as a dry-run-default CLI action.
+- **A2 durability classification uses structural signals only.** `classifyDurability(text)` (new `src/core/brain/gates/durability.ts`) flags transient operational content via language-agnostic shapes: filesystem temp paths (`/tmp/`, `*.tmp`, OS temp dirs), progress counters (`N/M`, `NN%`), run-id/timestamp-suffixed identifiers, byte/duration measurements as the dominant token class, and process-exit/status codes. Word lists are not compiled in; an optional `durability.denylist` config key accepts operator-supplied regexes. The gate runs inside `routeExtractedFacts` (the noisy automated path) before `writeSignal`; a rejected fact is not silently dropped - it is recorded via `appendLogEvent` with a dedicated event kind so `doctor` can surface rejection counts. Operator-initiated `brain_feedback` writes are NOT gated (the operator is not noise).
+- **A3 approval queue defaults off and reuses the signal file format verbatim.** With `write_approval.enabled=true`, `routeExtractedFacts` writes the identical frontmatter document to `Brain/pending/` instead of `Brain/inbox/`. Apply moves the file into `Brain/inbox/` unchanged (entity anchors were resolved at extraction time and live in the document); reject moves it to `Brain/retired/` with a rejection reason. New CLI verb `o2b brain pending list|apply|reject`. No new document schema.
+- **A4 advisory reuses `detectContradictions` as a pure function at write ingress.** `src/core/brain/health/contradiction.ts:250` already takes in-memory preferences and a Jaccard option; A4 loads confirmed preferences for the incoming signal's scope bucket only, runs the same pairwise similarity against the incoming principle, and returns an advisory (never blocks the write). The advisory surfaces in the `brain_feedback` MCP response and CLI output and is logged. Detection thresholds reuse the existing health-pass defaults.
+- **A5 fact retire mirrors `moveToRetired` for signals.** `retireSignal(vault, id, { reason, superseded_by? })` moves `Brain/inbox/sig-*.md` to `Brain/retired/`, rewrites frontmatter (`_status: "retired"`, `retired_at`, `retired_reason`, optional `superseded_by`, tag swap, alias for the old id) and appends an audit line, following `preference.ts:1005` conventions. Because the dream pass consumes `Brain/inbox/` only, the directory move IS the exclusion mechanism; retired signals stay readable through the existing retired-directory query fallback. CLI: `o2b brain signal retire <id> --reason <text> [--superseded-by <id>]`.
+- **B1 validates at the store choke point and fails loud in normalisation.** A new `assertValidVector(vector, context)` (in `src/core/search/vector-guard.ts`) rejects non-finite values and all-zero vectors with a new `SearchError` code `EMBEDDING_INVALID_VECTOR`; `vecUpsert` (`store.ts:821`) calls it after the existing dimension gate, and `semanticTopK` applies it to query vectors. `unitNormaliseInPlace` (`http-util.ts:48`) stops returning unnormalised zeros: zero-norm or non-finite input now throws the same typed error, because a silent all-zero embedding is exactly the misleading no-op fallback this project forbids.
+- **B2 threads an embed kind through the provider contract additively.** `EmbeddingProvider.embed(texts, kind?: "query" | "passage")` is an optional second parameter (backward compatible for any provider implementation). The openai-compat provider prepends the configured prefix per kind; `indexer.ts:601` passes `"passage"`, `semantic-phase.ts:94` passes `"query"`. New config keys `embedding_prefix_query` / `embedding_prefix_passage` (env twins included) default from the preset: a new optional `queryPrefix`/`passagePrefix` field pair on `EmbeddingModelPreset`, populated for e5-family entries. The active prefix pair is recorded in the index meta and a mismatch between stored and configured prefixes surfaces the existing reindex-required warning path, since stored vectors embedded without prefixes are not comparable to prefixed queries.
+- **C1 and C2 share one classification rework.** `classifyError` returns `{ category: "quota" | "rate_limit" | "auth" | "transient" | "fatal"; retriable: boolean; retryAfterMs: number | null; error: SearchError }`. The HTTP status and `Retry-After` header are carried as structured fields on the thrown error from `embedBatchOnce`: `SearchError` gains an additive optional constructor argument (`opts?: { status?: number; retryAfterMs?: number }`) exposed as readonly fields, so no message-string parsing remains anywhere in the classifier. 402 always classifies as quota; 429 classifies as quota only on protocol-token evidence in the response body (provider error codes such as `insufficient_quota`, which are wire-protocol identifiers, not natural language). Quota adds `SearchError` code `EMBEDDING_QUOTA_EXHAUSTED` with an actionable message (billing exhausted, semantic search degraded, check provider billing). C2 makes the retry loop honor `retryAfterMs` (capped) for rate-limit/transient retries, fail fast on quota, and enrich the implicit-semantic degrade warning (`semantic-phase.ts`) plus `searchErrorToMcp` (`search-tools.ts:400`) with the quota-specific actionable message. Explicit `--semantic` continues to throw the typed error - no silent lexical fallback on an explicit request.
+- **D1 is a thin wrapper, not a new engine.** `withDestructiveSnapshot(vault, label, op)` (in a new sibling `src/core/brain/snapshot-gate.ts`, keeping the 656-line engine module untouched) mints `runId = <label>-<isoSecondCompact>` via the existing `validateRunId`, calls `createSnapshot`, runs `op`, then `pruneSnapshots` with the configured retention. Snapshot failure aborts the operation with the existing typed snapshot errors - a destructive op never proceeds unsnapshotted. `deleteBySource` calls it around its confirm-path deletions (`source-cleanup.ts`); the A1 prune reuses it.
+- **D2 reuses remediation machinery and secure-by-default redaction.** Permission migration ships as a new `auto-safe` remediation step class (`harden-permissions`) in `health/remediation.ts`: an idempotent bounded walk (existing `stepCap` bounds work per run, so re-running resumes naturally) that chmods `Brain/` files to `0o600` and directories to `0o700`, dry-run by default through the existing `--remediate --dry-run` flow. The symlink lint adds a doctor issue code (`symlink-escape`) that reports vault-internal symlinks resolving outside the vault, reusing `ensureInsideVault` (`src/core/path-safety.ts`) semantics. MCP responses stop exposing `ctx.vault` absolute paths at the four `src/mcp/tools.ts` sites: the value is replaced by an opaque store reference derived from the existing device-id primitive plus a stable vault hash, with an `expose_host_paths=true` config escape hatch (resolved in `src/core/config.ts`, the vault-level config surface) for operators who depend on the raw path; the redaction default is on because MCP responses land in model context, which is exactly the leak surface the upstream fix targets. The prune surface for A1 ships under the existing entity CLI verb as a subcommand (dry-run default, `--confirm` to apply); the implementer wires it into whichever entity verb file already exists rather than creating a parallel verb.
+
+## File changes
+
+New files:
+- `src/core/brain/gates/durability.ts` - structural transient-content classifier (A2).
+- `src/core/brain/pending.ts` - approval queue staging/apply/reject (A3).
+- `src/core/brain/signal-retire.ts` - signal retire lifecycle (A5).
+- `src/core/search/vector-guard.ts` - vector validity kernel (B1).
+- `src/cli/brain/verbs/pending.ts` - pending queue CLI verb (A3).
+- `tests/*` mirrors for every new module.
+
+Modified files:
+- `src/core/brain/entities/canonical.ts` (+ `sanitizeEntityLabel`, structural label validation) and its intake call sites `src/core/brain/fact-extract.ts`, `src/core/brain/atomic-facts.ts`, entity creation path (A1).
+- `src/core/brain/fact-extract.ts` - durability gate + approval staging seam in `routeExtractedFacts` (A2, A3).
+- `src/core/brain/signal.ts` - write-ingress advisory hook surface (A4), shared by MCP/CLI feedback paths.
+- `src/core/brain/health/contradiction.ts` - export an incoming-vs-confirmed advisory helper reusing the existing pairwise kernel (A4).
+- `src/core/search/store.ts`, `src/core/search/embeddings/http-util.ts` - vector gate wiring (B1).
+- `src/core/search/embeddings/contract.ts`, `openai-compat.ts`, `presets.ts`, `src/core/search/indexer.ts`, `src/core/search/semantic-phase.ts`, `src/core/search/index.ts` (config keys), index meta - prefixes (B2).
+- `src/core/search/embeddings/openai-compat.ts`, `http-util.ts`, `src/core/search/types.ts`, `src/core/search/semantic-phase.ts`, `src/mcp/search-tools.ts` - quota classification and Retry-After handling (C1, C2).
+- `src/core/brain/snapshot.ts` (or sibling), `src/core/brain/source-cleanup.ts` - snapshot gate (D1).
+- `src/core/brain/health/remediation.ts`, `src/core/brain/doctor.ts`, `src/mcp/tools.ts`, `src/core/config.ts` or `src/core/search/index.ts` config surface - hardening (D2).
+- `src/cli/brain.ts`, `src/cli/brain/help-text.ts` - new verbs/flags registration (A1 prune surface, A3, A5, D2).
+- `README.md`, `CHANGELOG.md`, `package.json` + manifest mirrors via `scripts/sync-version.ts` - docs and version (final task).
+
+## Risks and open questions
+
+- **B2 reindex semantics**: adding passage prefixes invalidates stored vectors; the mismatch must surface through the existing reindex-required path, not silently mix prefixed queries with unprefixed passages. The implementer must verify how index meta records embedding parameters today (`embeddingHash`, dimension lock) and extend that mechanism rather than invent a parallel one.
+- **C1 quota-shaped 429 detection** varies by provider; the classifier stays conservative (default: 429 without protocol-token evidence remains a rate-limit) so false quota classifications cannot disable retries incorrectly.
+- **D2 redaction default-on** changes the VALUE of existing MCP response fields (shape unchanged). This is deliberate (security default) and gets a CHANGELOG callout plus the `expose_host_paths` escape hatch.
+- **A1 prune blast radius**: prune only removes nodes failing the structural validator and their edges; it never touches nodes that merely LOOK unusual. Dry-run default plus D1 snapshot gate bound the damage of a bad run.
+- **Gate chain ordering** in `routeExtractedFacts` is fixed as: dedup -> durability (A2) -> staging decision (A3) -> write; A4 advisory attaches to the operator-facing feedback path, not the extracted path, so the two never double-fire on one write.
diff --git a/docs/brainstorm/memory-write-path-integrity/plan.md b/docs/brainstorm/memory-write-path-integrity/plan.md
new file mode 100644
index 00000000..f9d12a53
--- /dev/null
+++ b/docs/brainstorm/memory-write-path-integrity/plan.md
@@ -0,0 +1,71 @@
+# Memory write-path integrity and store safety - implementation plan
+
+Task order is risk-first inside each cluster and respects the only two hard
+dependency edges: C1 before C2 (the handling layer consumes the classifier)
+and D1 before A1 (the entity prune runs behind the snapshot gate). Clusters
+are mutually independent; each task lands as one atomic conventional commit
+with its tests, formatted and lint-clean.
+
+Sequence: C1 -> C2 -> B1 -> B2 -> D1 -> D2 -> A1 -> A2 -> A3 -> A4 -> A5 -> L
+
+## Tasks
+
+### Task C1 - quota/billing error classification (`t_8880a68d`, p2)
+- **Files**: `src/core/search/embeddings/openai-compat.ts`, `src/core/search/embeddings/http-util.ts`, `src/core/search/types.ts`, tests under `tests/core/search/`.
+- **Acceptance**: `embedBatchOnce` carries HTTP status and `Retry-After` as structured fields (no message-string regex); `classifyError` returns `{ category, retriable, retryAfterMs, error }`; HTTP 402 and protocol-token-evidenced 429 classify as `quota` with new code `EMBEDDING_QUOTA_EXHAUSTED`, are non-retriable, and carry an actionable billing message; plain 429 stays `rate_limit` and retriable; 5xx stays `transient`; existing retry behavior for non-quota statuses is unchanged and all existing tests stay green.
+- **Depends on**: none.
+
+### Task C2 - Retry-After honoring and graceful semantic degrade (`t_144b680a`, p2)
+- **Files**: `src/core/search/embeddings/openai-compat.ts`, `src/core/search/semantic-phase.ts`, `src/mcp/search-tools.ts`, tests.
+- **Acceptance**: retry backoff uses `retryAfterMs` (bounded by a cap constant) when present for `rate_limit`/`transient` categories; `quota` fails fast with no retry; implicit semantic search degrades to lexical with a warning that names the category and the actionable message; explicit `--semantic` throws the typed error; `searchErrorToMcp` maps `EMBEDDING_QUOTA_EXHAUSTED` to its actionable message.
+- **Depends on**: C1.
+
+### Task B1 - vector validity gate (`t_e2b182b6`, p4)
+- **Files**: new `src/core/search/vector-guard.ts`, `src/core/search/store.ts`, `src/core/search/embeddings/http-util.ts`, `src/core/search/types.ts`, tests.
+- **Acceptance**: `assertValidVector` rejects non-finite and all-zero vectors with new code `EMBEDDING_INVALID_VECTOR`; `vecUpsert` and `semanticTopK` invoke it; `unitNormaliseInPlace` throws the same typed error on zero-norm or non-finite input instead of returning zeros; a NaN vector can no longer reach the vec table (proven by test through the store API).
+- **Depends on**: none.
+
+### Task B2 - e5 instruction prefixes (`t_3beb374c`, p3)
+- **Files**: `src/core/search/embeddings/contract.ts`, `openai-compat.ts`, `presets.ts`, `configured-provider.ts`, `src/core/search/indexer.ts`, `src/core/search/semantic-phase.ts`, `src/core/search/index.ts`, index meta handling in `src/core/search/store.ts` or `indexer.ts`, tests.
+- **Acceptance**: `embed(texts, kind?)` is additive; indexer embeds with `"passage"`, semantic phase with `"query"`; prefixes resolve preset-first (`queryPrefix`/`passagePrefix` on the e5 preset) with `embedding_prefix_query`/`embedding_prefix_passage` config/env overrides; the active prefix pair is persisted in index meta and a stored-vs-configured mismatch surfaces the reindex-required warning; with no preset match and no config the behavior is byte-identical to today.
+- **Depends on**: none (C1/C2 touch the same file; land after them to avoid churn).
+
+### Task D1 - snapshot-before-destructive-write gate (`t_7965b04b`, p4)
+- **Files**: new `src/core/brain/snapshot-gate.ts`, `src/core/brain/source-cleanup.ts`, tests.
+- **Acceptance**: `withDestructiveSnapshot(vault, label, op)` mints a validated run id, snapshots before `op`, prunes after with configured retention, and aborts (typed error, no partial deletion) when snapshotting fails; `deleteBySource` with `confirm: true` produces a snapshot before any `rmSync` and reports the snapshot path in its result; dry-run path takes no snapshot.
+- **Depends on**: none.
+
+### Task D2 - store hardening (`t_29a63073`, p4)
+- **Files**: `src/core/brain/health/remediation.ts`, `src/core/brain/doctor.ts`, `src/mcp/tools.ts`, config surface (`src/core/config.ts`), `src/cli/brain/help-text.ts` if flags change, tests.
+- **Acceptance**: a `harden-permissions` auto-safe remediation step chmods existing `Brain/` files to `0o600` and directories to `0o700`, idempotent and bounded by `stepCap` (re-run resumes), dry-run listed before apply; doctor reports a `symlink-escape` issue for any vault-internal symlink resolving outside the vault; the four `src/mcp/tools.ts` sites return an opaque store reference instead of the absolute vault path by default, with `expose_host_paths=true` restoring the raw value.
+- **Depends on**: none.
+
+### Task A1 - entity label quality and prune (`t_657b365e`, p4)
+- **Files**: `src/core/brain/entities/canonical.ts`, `src/core/brain/fact-extract.ts`, `src/core/brain/atomic-facts.ts`, entity-creation path, prune subcommand under the existing entity CLI verb (dry-run default), `src/core/brain/doctor.ts` for candidate visibility, tests.
+- **Acceptance**: `sanitizeEntityLabel` strips surrounding Markdown emphasis/heading markers and surrounding punctuation before normalization at every label-intake boundary; structurally-junk labels (empty after strip, no letter/digit in any script, over length bound, or in the operator-supplied `entities.label_denylist`) are rejected with a typed error at creation and a logged skip at anchoring; `entityIdentityKey` output for every currently-valid label is byte-identical to before; the prune lists malformed historical nodes in dry-run, and on confirm removes nodes plus their edges inside `withDestructiveSnapshot` leaving no orphaned references (doctor-verified in test).
+- **Depends on**: D1.
+
+### Task A2 - durability gate (`t_375e98fd`, p3)
+- **Files**: new `src/core/brain/gates/durability.ts`, `src/core/brain/fact-extract.ts`, log event kind registration, doctor visibility, tests.
+- **Acceptance**: `classifyDurability` flags transient content via structural signals only (temp paths, progress counters, dominant measurement tokens, run-id shapes, exit-status shapes) with zero built-in natural-language word lists; optional `durability.denylist` config regexes extend it; `routeExtractedFacts` skips flagged facts before `writeSignal`, logging each skip with a dedicated event kind; operator `brain_feedback` writes are not gated; classification is pure and deterministic (property: same input, same verdict, no I/O).
+- **Depends on**: none (same file as A3; land before it).
+
+### Task A3 - write-approval pending queue (`t_e540b093`, p3)
+- **Files**: new `src/core/brain/pending.ts`, `src/core/brain/fact-extract.ts`, new `src/cli/brain/verbs/pending.ts`, `src/cli/brain.ts`, `src/cli/brain/help-text.ts`, `src/core/brain/paths.ts` (pending dir), tests.
+- **Acceptance**: with `write_approval.enabled=true` extracted signals land in `Brain/pending/` with unchanged frontmatter; default off preserves today's direct-to-inbox behavior byte-for-byte; `o2b brain pending list` shows queued items, `apply <id>` moves to `Brain/inbox/` preserving entity anchors and dedup hash, `reject <id> --reason` moves to `Brain/retired/` with reason; applying a missing id is a typed error, not a no-op.
+- **Depends on**: A2 (gate chain order inside `routeExtractedFacts`).
+
+### Task A4 - write-time conflict advisory (`t_f79b4fe0`, p3)
+- **Files**: `src/core/brain/health/contradiction.ts` (advisory helper export), the feedback write path in `src/core/brain/signal.ts` and its MCP/CLI surfacing, tests.
+- **Acceptance**: writing a feedback signal whose principle contradicts a confirmed same-scope preference (per the existing pairwise kernel and thresholds) returns an advisory naming the conflicting preference id; the write itself always proceeds; the advisory appears in the `brain_feedback` MCP response and CLI output and is logged; no advisory fires for non-conflicting writes (test both directions); the extracted-fact path does not double-fire the advisory.
+- **Depends on**: none.
+
+### Task A5 - fact signal retire lifecycle (`t_66c12a67`, p3)
+- **Files**: new `src/core/brain/signal-retire.ts`, CLI verb wiring (`src/cli/brain.ts`, `help-text.ts`, verb file), tests.
+- **Acceptance**: `retireSignal` moves `Brain/inbox/sig-*.md` to `Brain/retired/` with `_status: "retired"`, `retired_at`, `retired_reason`, optional `superseded_by`, tag swap and old-id alias, refusing paths outside the inbox dir; an audit line is appended; retired signals stop being dream-pass intake but remain queryable through the retired-directory fallback; retiring an already-retired or missing id is a typed error.
+- **Depends on**: none.
+
+### Task L - docs, CHANGELOG, version bump
+- **Files**: `README.md`, `CHANGELOG.md`, `package.json`, mirrored manifests via `bun run scripts/sync-version.ts`, `docs/` pages the units touch (`cli-reference.md`, `mcp.md`, `stability.md` as applicable).
+- **Acceptance**: one `## [1.32.0]` CHANGELOG entry with link reference covering all eleven units; README gains short sections for the new surfaces; `bun run sync-version:check` passes; version 1.32.0 (1.31.0 is reserved by the open pull request #138).
+- **Depends on**: all previous tasks.
diff --git a/docs/brainstorm/memory-write-path-integrity/variants.md b/docs/brainstorm/memory-write-path-integrity/variants.md
new file mode 100644
index 00000000..fb6c5f94
--- /dev/null
+++ b/docs/brainstorm/memory-write-path-integrity/variants.md
@@ -0,0 +1,67 @@
+# Memory write-path integrity and store safety - variant audit trail
+
+Consultant: Claude Code (`claude -p`), prompt in `cli-output/prompt.md`, raw
+output in `cli-output/claude.md`. Three variants were requested for the wave
+architecture as a whole (shared abstractions vs isolated changes), not for
+the worth of individual units. The fallback consultant (Codex) was not
+invoked because the primary run succeeded with three parseable variants.
+
+## Variant 1: Unified WriteGate framework
+
+- **Approach**: one cross-cutting gate framework (`src/core/gates/`) with a generic `Gate<T>` interface, a composable `GatePipeline`, and a single typed `WriteRejection` error hierarchy. All eleven units are expressed as gate stages plugged into this pipeline; every persist path (vault writes, `vecUpsert`, `deleteBySource`) is refactored to run through it.
+- **Trade-offs**:
+ - Pro: maximally DRY; one place to reason about "what can reject a write"; uniform rejection logging and doctor visibility for free.
+ - Pro: a single error taxonomy makes CLI/MCP surfacing consistent across all units.
+ - Con: the units span three genuinely different subsystems (Markdown vault writes, the sqlite-vec store, an HTTP embeddings client) with different payload types and failure semantics; a shared `Gate<T>` interface is speculative generality that mostly holds `unknown`.
+ - Con: the framework becomes a serialization point - every unit's atomic commit depends on it, so a design flaw discovered late forces rework across the whole wave.
+ - Con: units t_3beb374c (e5 prefixes), t_66c12a67 (fact retire), and t_29a63073 (permission migration) are not gates at all and get shoehorned in or left inconsistent.
+- **Complexity**: large
+- **Risk**: high
+
+## Variant 2: Per-unit isolated changes
+
+- **Approach**: each unit lands independently at its natural existing choke point with no new shared modules: extend `normalizeEntityName` in place, add checks inside `vecUpsert`, patch `classifyError` twice (once per embeddings unit), wrap `deleteBySource` with a direct `createSnapshot` call, and so on. Error codes are added ad hoc per subsystem as each unit needs them.
+- **Trade-offs**:
+ - Pro: trivially atomic commits with no ordering constraints; any unit can be dropped or reverted without touching the others.
+ - Pro: smallest possible diff per unit; matches the "improvement, not net-new" scoping of several units.
+ - Con: the brain write path ends up with five uncoordinated pre-persist checks with inconsistent rejection surfacing - exactly the "scattered per-call-site checks" the project constraints forbid.
+ - Con: t_8880a68d and t_144b680a both rework `classifyError`; done independently they conflict or duplicate Retry-After/quota parsing.
+ - Con: rejection logging conventions diverge per unit, making doctor/hygiene visibility (required by the no-silent-drop constraint) inconsistent.
+- **Complexity**: medium
+- **Risk**: medium
+
+## Variant 3: Cluster-scoped kernels, per-unit atomic commits
+
+- **Approach**: group the eleven units into four subsystem clusters and introduce a small shared kernel only where units provably share a choke point, then land each unit as an atomic commit on top of its kernel. Brain write path gets a light gate chain with one logged-skip convention; the vec store gets a `validateVector` kernel plus preset-aware prefix config; the embeddings client gets one `classifyError` rework into `{category, retriable, retryAfterMs}` consumed by both resilience units in sequence; store safety gets a `withSnapshot`-style wrapper over the existing engine, reused by `deleteBySource` and the entity prune, with the permission migration landing as a remediation pass.
+- **Trade-offs**:
+ - Pro: DRY exactly where coupling is real (the two embeddings units, the multiple brain gates, the multiple snapshot consumers) without inventing a cross-subsystem abstraction.
+ - Pro: preserves per-unit atomic commits - each kernel is itself a small commit, units within a cluster stack on it, clusters remain mutually independent, so partial shipping stays possible.
+ - Pro: error-type design stays subsystem-native (`SearchError` codes for search/embeddings, typed brain-side rejections for vault writes), honoring existing conventions instead of unifying them artificially.
+ - Con: requires deciding cluster boundaries and kernel interfaces up front, and sequencing within clusters (classifier before handling, gate chain before the gates that plug into it).
+ - Con: two error vocabularies coexist; a reviewer must understand which subsystem a rejection belongs to.
+- **Complexity**: medium
+- **Risk**: low
+
+## Consultant recommendation
+
+Variant 3. "The wave's units cluster naturally along OSB's existing module
+seams (brain vault, search store, embeddings client, snapshot engine), and
+Variant 3 puts shared abstractions only at choke points that two or more
+units actually share - satisfying the repo's 'shared choke points over
+scattered checks' and typed-error constraints without Variant 1's
+speculative cross-subsystem framework or Variant 2's duplicated
+`classifyError` rework and uncoordinated gate sprawl. It also keeps every
+unit an independently revertable atomic commit on one branch, which is
+exactly what an 11-unit single-release wave needs when any one unit could
+stall in review." (quoted verbatim from the consultant output)
+
+## Orchestrator decision
+
+Variant 3 is adopted without override. Project context reinforces the
+recommendation: v1.30.1 explicitly removed all import cycles and decomposed
+oversized modules, so a new cross-subsystem framework (Variant 1) would cut
+against the freshly-established one-directional layering, while Variant 2's
+double rework of `classifyError` and scattered brain-write checks would
+recreate the DRY violations the operator's brief forbids. The dependency
+edges accepted with Variant 3 (classifier before handling, snapshot gate
+before prune) are recorded in `plan.md`.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 1396f532..dd33f371 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -237,6 +237,18 @@ o2b search <query> --expand deterministic lex/vec/hyde expansion of a bare que
Wikilinks to frontmatter `aliases:` resolve at index materialization (schema v7): exact paths always win, a real basename is never shadowed, collisions resolve first-wins by sorted path, and `o2b search status` counts the pass via `IndexStats.aliasResolved`. Bridge discovery and clusters also run as maintenance-lane tasks after `reindex`. Self-tuning only changes behavior under `search_self_tuning_enabled` (or `OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING=1`); an explicit `--expand`/`expand` always wins over the tuned default. Every surface appends one run-level record to `Brain/metrics/<surface>.jsonl` - the dashboard data contract documented in `docs/metrics.md`.
+### Write-path integrity and store safety (since v1.32.0)
+
+```text
+o2b brain pending list | apply <id> | reject <id> --reason <text> - review the opt-in write-approval queue (`write_approval.enabled`); staged extracted signals live in Brain/pending/, apply moves the unchanged document to the inbox, reject moves it to Brain/retired/ with the reason
+o2b brain signal retire <id> --reason <text> [--superseded-by <id>] - move an inbox signal to Brain/retired/ with retire frontmatter (_status, retired_at, retired_reason, optional superseded_by, old-id alias); retired signals leave dream intake but stay queryable
+o2b brain entity prune [--confirm] [--json] - list entity nodes whose labels fail the structural quality gate (dry-run default); --confirm removes nodes and their edges behind the snapshot gate and reports the recovery point
+o2b brain forget-source --confirm now snapshots Brain/ before any deletion and reports the snapshot run id; dry runs take no snapshot
+o2b brain doctor gains the `symlink-escape` error (vault-internal symlink resolving outside the vault root) and the `entity-label-malformed` warning (prune candidates); `--remediate` gains the auto-safe `harden-permissions` step (owner-only chmod for existing Brain/ files, idempotent, step-capped, dry-run first)
+```
+
+Extracted facts pass a deterministic durability gate before persisting: structural signals only (temp paths, progress counters, run-id and timestamp shapes, measurement-token dominance, exit-status shapes), extendable with `durability.denylist` regexes; rejections log `durability-skip` events and are surfaced by count in the route result. Entity labels are sanitized (`**Foo**` becomes `Foo`) and structurally validated at every intake boundary, with `entities.label_denylist` as the only vocabulary source. Feedback writes that closely resemble a confirmed same-scope preference return a conflict advisory (and log `write-conflict-advisory`) while the write proceeds. Embedding-side: `embedding_prefix_query`/`embedding_prefix_passage` (env twins, e5 preset defaults) control instruction prefixes, invalid vectors are rejected with `EMBEDDING_INVALID_VECTOR`, and quota exhaustion surfaces as non-retriable `EMBEDDING_QUOTA_EXHAUSTED` with Retry-After-aware backoff for plain rate limits.
+
## Stability and trust (since v1.0.0)
```text
diff --git a/docs/mcp.md b/docs/mcp.md
index a0ab4471..d9278e21 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -483,3 +483,12 @@ Both servers reuse the same backing CLI (`o2b mcp --scope writer` vs the default
the prior or the new file, never a torn hybrid.
- MCP tools can declare lightweight output contracts; declared contracts are
validated against `structuredContent` before the text mirror is emitted.
+- Since v1.32.0 the `vault_path` fields returned by the core tools carry a
+ stable opaque store reference (`vault://<hash>`) instead of the absolute
+ host path, because tool responses land in model context. Set
+ `expose_host_paths: true` (or `OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS=true`)
+ to restore the raw path.
+- Since v1.32.0 `brain_feedback` responses include a conflict advisory when
+ the incoming principle closely resembles a confirmed same-scope preference
+ (the write still proceeds); the advisory names the preference id and the
+ similarity evidence.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index afc9c5f7..17cd41dc 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.31.0",
+ "version": "1.32.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 161b8609..f0ef3f18 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.31.0",
+ "version": "1.32.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.yaml
index 663b4189..a8bbabee 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.31.0"
+version: "1.32.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 3bf0ff62..e2dd8cab 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.31.0",
+ "version": "1.32.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 663b4189..a8bbabee 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.31.0"
+version: "1.32.0"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index c082727a..3c3174e3 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.31.0"
+version = "1.32.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/cli/brain.ts b/src/cli/brain.ts
index f1b8664a..12218627 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -117,6 +117,8 @@ import {
cmdBrainAgenda,
cmdBrainToday,
cmdBrainApplyMarkers,
+ cmdBrainPending,
+ cmdBrainSignal,
cmdBrainAttentionFlows,
cmdBrainSessionDescribe,
cmdBrainSessionExpand,
@@ -372,6 +374,10 @@ export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promis
return await cmdBrainToday(rest);
case "apply-markers":
return await cmdBrainApplyMarkers(rest);
+ case "pending":
+ return await cmdBrainPending(rest);
+ case "signal":
+ return await cmdBrainSignal(rest);
case "session-grep":
return await cmdBrainSessionGrep(rest);
case "session-describe":
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 9d7dc048..7667aa18 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -75,7 +75,7 @@ Brain verbs (observing memory):
mcp-landscape List MCP servers configured across the vault (packages, env names)
scan-inline Capture @osb markers from folders listed under notes.read_paths in _brain.yaml
import-session Replay signals from a registered agent session .jsonl (or directory)
- entity Canonical entity registry: set, get, list, relate, archive
+ entity Canonical entity registry: set, get, list, relate, archive, prune
session-hook Capture one runtime hook payload from stdin (internal hook bridge)
import-claude-memory Import metadata.type:feedback MEMORY entries as confirmed preferences
page-dedup Detect (and optionally merge) near-duplicate vault pages
@@ -98,6 +98,8 @@ Brain verbs (observing memory):
agenda Synthesize agenda conflicts/focus blocks from provided events
today Today dashboard: due obligations, open loops, recent activity, totals
apply-markers Apply @osb set frontmatter write-backs (report by default; --apply writes)
+ pending Review the write-approval queue: list | apply <id> | reject <id>
+ signal Fact signal lifecycle: retire <id> --reason <text>
session-grep Search imported session recall turns and summaries
session-describe Describe an imported session recall DAG
session-expand Expand a session recall node to source turns
@@ -489,13 +491,16 @@ export const VERB_HELP: Record<string, string> = {
"entry) exits 2 — never silent overwrites.\n" +
"Default is --dry-run; --apply requires --yes in non-interactive mode.\n",
entity:
- "usage: o2b brain entity <set|get|list|relate|archive> [args]\n" +
+ "usage: o2b brain entity <set|get|list|relate|archive|prune> [args]\n" +
" set <category> <name> [--alias <a>]... [--body <md>] [--confidence <c>] [--json]\n" +
" get <name-or-alias> [--category <c>] [--json] exit 2 when not found\n" +
" list [--category <c>] [--status active|archived] [--json]\n" +
" relate <from> <relation> <to> [--from-category <c>] [--to-category <c>] [--json]\n" +
" archive <name-or-alias> [--restore] [--category <c>] [--json]\n" +
- "One canonical entity per (category, name); aliases resolve to the canonical record.",
+ " prune [--confirm] [--json] dry-run default; snapshot before removal\n" +
+ "One canonical entity per (category, name); aliases resolve to the canonical record.\n" +
+ "Labels are decoration-stripped and quality-gated on set; prune removes historical\n" +
+ "malformed nodes and their edges. Denylist: entities.label_denylist config key.",
"import-session":
"usage: o2b brain import-session <path> [--vault <vault>]\n" +
" [--format auto|<registered-adapter>]\n" +
@@ -687,6 +692,24 @@ export const VERB_HELP: Record<string, string> = {
"(annotated) so a re-run is idempotent. Unresolvable or invalid targets are\n" +
"reported with an error code and candidates and left unconsumed. Source files\n" +
"come from --path (repeatable) or notes.read_paths.\n",
+ pending:
+ "usage: o2b brain pending list [--vault <path>] [--json]\n" +
+ " o2b brain pending apply <id> [--vault <path>] [--json]\n" +
+ " o2b brain pending reject <id> --reason <text> [--vault <path>] [--json]\n" +
+ "Review the opt-in write-approval queue (write_approval.enabled). When the\n" +
+ "toggle is on, extracted signals are staged into Brain/pending/ instead of\n" +
+ "Brain/inbox/. list shows the staged signals; apply moves one into\n" +
+ "Brain/inbox/ unchanged (entity anchors and dedup hash preserved); reject\n" +
+ "moves it to Brain/retired/ with retire-shaped frontmatter. Applying or\n" +
+ "rejecting a missing id exits 2 (never a silent no-op).\n",
+ signal:
+ "usage: o2b brain signal retire <id> --reason <text> [--superseded-by <id>] [--vault <path>] [--json]\n" +
+ "Retire an extracted fact signal: move Brain/inbox/sig-*.md into\n" +
+ "Brain/retired/ with retire-shaped frontmatter (_status, retired_at,\n" +
+ "retired_reason, optional superseded_by, old-id alias). The directory move\n" +
+ "excludes it from the dream pass while it stays readable in Brain/retired/.\n" +
+ "Retiring a missing, already-retired, or non-signal id exits 2 (never a\n" +
+ "silent no-op).\n",
agenda:
"usage: o2b brain agenda --events <file|-> [args]\n" +
"Deterministic agenda synthesis over caller-provided calendar events (JSON array or {events:[...]}).\n" +
diff --git a/src/cli/brain/verbs/doctor.ts b/src/cli/brain/verbs/doctor.ts
index 3303e1de..672595b8 100644
--- a/src/cli/brain/verbs/doctor.ts
+++ b/src/cli/brain/verbs/doctor.ts
@@ -3,6 +3,7 @@ import { runDoctor } from "../../../core/brain/doctor.ts";
import {
applyRemediation,
collectDriftedSlugs,
+ collectWidePermissions,
planRemediation,
} from "../../../core/brain/health/remediation.ts";
import { loadBrainConfigDetailed, resolveHealth } from "../../../core/brain/policy.ts";
@@ -84,6 +85,7 @@ function runRemediate(
const plan = planRemediation(
{
driftedSlugs: collectDriftedSlugs(vault),
+ widePermissions: collectWidePermissions(vault),
contradictions: (sh?.contradictions ?? []).map((c) => ({ aId: c.aId, bId: c.bId })),
staleClaims: (sh?.staleClaims ?? []).map((s) => ({ id: s.id })),
conceptGaps: (sh?.conceptGaps ?? []).map((g) => ({ term: g.term })),
diff --git a/src/cli/brain/verbs/entity.ts b/src/cli/brain/verbs/entity.ts
index 227c66f4..183a2d40 100644
--- a/src/cli/brain/verbs/entity.ts
+++ b/src/cli/brain/verbs/entity.ts
@@ -13,7 +13,17 @@ import {
upsertEntity,
} from "../../../core/brain/entities/registry.ts";
import { BRAIN_ENTITY_STATUS, type BrainEntity } from "../../../core/brain/entities/types.ts";
-import { brainVerbContext, fail, normalizeFlagString, ok, okJson, parse } from "../helpers.ts";
+import { pruneEntityLabels } from "../../../core/brain/entities/label-hygiene.ts";
+import {
+ brainVerbContext,
+ fail,
+ info,
+ normalizeFlagString,
+ ok,
+ okJson,
+ parse,
+ usageError,
+} from "../helpers.ts";
function entityPayload(entity: BrainEntity): Record<string, unknown> {
return {
@@ -51,10 +61,12 @@ export async function cmdBrainEntity(argv: string[]): Promise<number> {
return entityRelate(rest);
case "archive":
return entityArchive(rest);
+ case "prune":
+ return entityPrune(rest);
default:
- return fail(
+ return usageError(
"brain entity requires a subcommand: set <category> <name> | get <name> | list | " +
- "relate <from> <relation> <to> | archive <name> [--restore]",
+ "relate <from> <relation> <to> | archive <name> [--restore] | prune [--confirm]",
);
}
}
@@ -191,6 +203,69 @@ function entityRelate(argv: string[]): number {
}
}
+function entityPrune(argv: string[]): number {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ confirm: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const { vault } = brainVerbContext(flags);
+ const confirm = flags["confirm"] === true;
+ try {
+ const result = pruneEntityLabels(vault, { confirm, now: new Date() });
+ if (flags["json"]) {
+ okJson({
+ confirmed: result.confirmed,
+ candidates: result.candidates.map((c) => ({
+ id: c.id,
+ category: c.category,
+ name: c.name,
+ status: c.status,
+ reason: c.reason,
+ path: c.path,
+ inbound_references: [...c.inboundReferences],
+ })),
+ removed: [...result.removed],
+ edges_stripped: result.edgesStripped,
+ snapshot_run_id: result.snapshotRunId,
+ snapshot_path: result.snapshotPath,
+ });
+ return 0;
+ }
+ if (result.candidates.length === 0) {
+ ok("entity prune: no malformed labels found");
+ return 0;
+ }
+ if (result.confirmed) {
+ ok(`entity prune: removed ${result.removed.length} node(s)`);
+ for (const c of result.candidates) ok(` - ${c.id} (${c.reason}) ${JSON.stringify(c.name)}`);
+ if (result.edgesStripped > 0) ok(` stripped ${result.edgesStripped} inbound edge(s)`);
+ if (result.snapshotRunId) {
+ ok(` recovery point: snapshot ${result.snapshotRunId}`);
+ if (result.snapshotPath) info(` ${result.snapshotPath}`);
+ }
+ return 0;
+ }
+ ok(`entity prune (DRY RUN): ${result.candidates.length} malformed label(s) WOULD be removed:`);
+ for (const c of result.candidates) {
+ const edges =
+ c.inboundReferences.length > 0
+ ? `, ${c.inboundReferences.length} inbound edge(s) from ${c.inboundReferences.join(", ")}`
+ : "";
+ ok(` - ${c.id} (${c.reason}) ${JSON.stringify(c.name)}${edges}`);
+ }
+ info(" re-run with --confirm to remove (a snapshot is taken first)");
+ return 0;
+ } catch (exc) {
+ const message = `brain entity prune failed: ${(exc as Error).message}`;
+ if (flags["json"]) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
+
function entityArchive(argv: string[]): number {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
diff --git a/src/cli/brain/verbs/feedback.ts b/src/cli/brain/verbs/feedback.ts
index 5ee15e19..8931e891 100644
--- a/src/cli/brain/verbs/feedback.ts
+++ b/src/cli/brain/verbs/feedback.ts
@@ -1,6 +1,7 @@
import { readFileSync } from "node:fs";
import { mirrorSignal, resolveSharedNamespace } from "../../../core/brain/shared-namespace.ts";
import { resolveEffectiveScope, writeSignal } from "../../../core/brain/signal.ts";
+import { adviseIncomingFeedback } from "../../../core/brain/write-advisory.ts";
import { loadFeedbackDefaultScopeSafe } from "../../../core/brain/policy.ts";
import { appendLogEvent } from "../../../core/brain/log.ts";
import { writePreference } from "../../../core/brain/preference.ts";
@@ -109,6 +110,15 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {
process.stderr.write(`warning: append feedback log failed: ${(err as Error).message}\n`);
}
+ // Write-time conflict advisory (A4): non-blocking, computed BEFORE any
+ // force-confirmed write so it never matches the pref this call creates.
+ const advisory = adviseIncomingFeedback(vault, {
+ principle: String(flags["principle"]),
+ ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),
+ agent,
+ now,
+ });
+
let prefResult: { path: string; id: string } | null = null;
if (flags["force-confirmed"]) {
try {
@@ -151,6 +161,7 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {
signal_path: sigResult.path,
signal_id: sigResult.id,
...(mirror !== undefined ? { mirror } : {}),
+ ...(advisory !== null ? { advisory } : {}),
...(prefResult ? { preference_path: prefResult.path, preference_id: prefResult.id } : {}),
});
return 0;
@@ -160,6 +171,15 @@ export async function cmdBrainFeedback(argv: string[]): Promise<number> {
if (mirror !== undefined) {
ok(`mirror: ${mirror}`);
}
+ if (advisory !== null) {
+ const where = advisory.scope ?? "(unscoped)";
+ ok(
+ `advisory: incoming principle resembles ${advisory.conflicts.length} confirmed ${where} preference(s)`,
+ );
+ for (const c of advisory.conflicts) {
+ ok(` - ${c.pref_id} (jaccard ${c.jaccard.toFixed(3)})`);
+ }
+ }
if (prefResult) {
ok(`preference: ${prefResult.path}`);
ok(`status: confirmed`);
diff --git a/src/cli/brain/verbs/forget-source.ts b/src/cli/brain/verbs/forget-source.ts
index 8f59c492..c6653147 100644
--- a/src/cli/brain/verbs/forget-source.ts
+++ b/src/cli/brain/verbs/forget-source.ts
@@ -89,6 +89,8 @@ export async function cmdBrainForgetSource(argv: string[]): Promise<number> {
deleted: [...plan.deleted],
manifest_entry_removed: plan.manifestEntryRemoved,
audit_record_id: plan.auditRecordId,
+ snapshot_run_id: plan.snapshotRunId,
+ snapshot_path: plan.snapshotPath,
});
return 0;
}
@@ -107,6 +109,10 @@ export async function cmdBrainForgetSource(argv: string[]): Promise<number> {
for (const p of plan.originals) info(` - ${p}`);
}
if (plan.auditRecordId) ok(` audit: ${plan.auditRecordId}`);
+ if (plan.snapshotRunId) {
+ ok(` recovery point: snapshot ${plan.snapshotRunId}`);
+ if (plan.snapshotPath) info(` ${plan.snapshotPath}`);
+ }
return 0;
}
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index 38043f66..27f2d7f5 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -102,6 +102,8 @@ export { cmdBrainObligation } from "./obligation.ts";
export { cmdBrainAgenda } from "./agenda.ts";
export { cmdBrainToday } from "./today.ts";
export { cmdBrainApplyMarkers } from "./apply-markers.ts";
+export { cmdBrainPending } from "./pending.ts";
+export { cmdBrainSignal } from "./signal.ts";
export {
cmdBrainSessionDescribe,
cmdBrainSessionExpand,
diff --git a/src/cli/brain/verbs/pending.ts b/src/cli/brain/verbs/pending.ts
new file mode 100644
index 00000000..5ca9f469
--- /dev/null
+++ b/src/cli/brain/verbs/pending.ts
@@ -0,0 +1,139 @@
+/**
+ * `o2b brain pending <list|apply|reject>` - the write-approval queue surface
+ * (A3, t_e540b093). Thin CLI wrapper over `src/core/brain/pending.ts`.
+ *
+ * When `write_approval.enabled` is on, extracted signals are staged into
+ * `Brain/pending/`; these verbs let an operator review the queue: `list` shows
+ * the staged signals, `apply <id>` moves one into `Brain/inbox/` unchanged, and
+ * `reject <id> --reason <text>` moves it to `Brain/retired/`. A missing id is a
+ * typed error surfaced as exit 2 (not a silent no-op).
+ */
+
+import {
+ applyPending,
+ listPending,
+ PendingSignalNotFoundError,
+ rejectPending,
+} from "../../../core/brain/pending.ts";
+import {
+ brainVerbContext,
+ fail,
+ normalizeFlagString,
+ ok,
+ okJson,
+ parse,
+ usageError,
+} from "../helpers.ts";
+
+export async function cmdBrainPending(argv: string[]): Promise<number> {
+ const sub = argv[0];
+ const rest = argv.slice(1);
+ switch (sub) {
+ case "list":
+ return pendingList(rest);
+ case "apply":
+ return pendingApply(rest);
+ case "reject":
+ return pendingReject(rest);
+ default:
+ return usageError(
+ "brain pending requires a subcommand: list | apply <id> | reject <id> --reason <text>",
+ );
+ }
+}
+
+function pendingList(argv: string[]): number {
+ const { flags } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ });
+ const { vault } = brainVerbContext(flags);
+ try {
+ const entries = listPending(vault);
+ if (flags["json"]) {
+ okJson({
+ pending: entries.map((e) => ({
+ id: e.id,
+ topic: e.signal.topic,
+ principle: e.signal.principle,
+ created_at: e.signal.created_at,
+ path: e.path,
+ })),
+ total: entries.length,
+ });
+ } else if (entries.length === 0) {
+ ok("no pending signals");
+ } else {
+ for (const e of entries) ok(`${e.id} ${e.signal.topic} ${e.signal.principle}`);
+ }
+ return 0;
+ } catch (exc) {
+ const message = `brain pending list failed: ${(exc as Error).message}`;
+ if (flags["json"]) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
+
+function pendingApply(argv: string[]): number {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ });
+ if (positional.length < 1) return usageError("brain pending apply requires an <id> argument");
+ const { vault } = brainVerbContext(flags);
+ try {
+ const res = applyPending(vault, positional[0]!);
+ if (flags["json"]) {
+ okJson({ id: res.id, path: res.path, status: "applied" });
+ } else {
+ ok(`applied: ${res.id}`);
+ }
+ return 0;
+ } catch (exc) {
+ if (exc instanceof PendingSignalNotFoundError) {
+ process.stderr.write(`${exc.message}\n`);
+ return 2;
+ }
+ const message = `brain pending apply failed: ${(exc as Error).message}`;
+ if (flags["json"]) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
+
+function pendingReject(argv: string[]): number {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ reason: { type: "string" },
+ json: { type: "boolean" },
+ });
+ if (positional.length < 1) return usageError("brain pending reject requires an <id> argument");
+ const reason = normalizeFlagString(flags["reason"]);
+ if (reason === null) return usageError("brain pending reject requires --reason <text>");
+ const { vault } = brainVerbContext(flags);
+ try {
+ const res = rejectPending(vault, positional[0]!, reason, { now: new Date() });
+ if (flags["json"]) {
+ okJson({ id: res.id, path: res.path, status: "rejected", reason });
+ } else {
+ ok(`rejected: ${res.id}`);
+ }
+ return 0;
+ } catch (exc) {
+ if (exc instanceof PendingSignalNotFoundError) {
+ process.stderr.write(`${exc.message}\n`);
+ return 2;
+ }
+ const message = `brain pending reject failed: ${(exc as Error).message}`;
+ if (flags["json"]) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
diff --git a/src/cli/brain/verbs/signal.ts b/src/cli/brain/verbs/signal.ts
new file mode 100644
index 00000000..5f0c433d
--- /dev/null
+++ b/src/cli/brain/verbs/signal.ts
@@ -0,0 +1,89 @@
+/**
+ * `o2b brain signal <retire>` - the fact signal lifecycle surface
+ * (A5, t_66c12a67). Thin CLI wrapper over `src/core/brain/signal-retire.ts`.
+ *
+ * `retire <id> --reason <text> [--superseded-by <id>]` moves an extracted
+ * fact signal from `Brain/inbox/` into `Brain/retired/` with retire
+ * frontmatter, excluding it from the dream pass while keeping it readable.
+ * A missing / already-retired / non-signal id is a typed error surfaced as
+ * exit 2 (not a silent no-op).
+ */
+
+import {
+ InvalidSignalIdError,
+ retireSignal,
+ SignalAlreadyRetiredError,
+ SignalNotFoundError,
+} from "../../../core/brain/signal-retire.ts";
+import {
+ brainVerbContext,
+ fail,
+ normalizeFlagString,
+ ok,
+ okJson,
+ parse,
+ resolveBrainAgent,
+ usageError,
+} from "../helpers.ts";
+
+export async function cmdBrainSignal(argv: string[]): Promise<number> {
+ const sub = argv[0];
+ const rest = argv.slice(1);
+ switch (sub) {
+ case "retire":
+ return signalRetire(rest);
+ default:
+ return usageError("brain signal requires a subcommand: retire <id> --reason <text>");
+ }
+}
+
+function signalRetire(argv: string[]): number {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ reason: { type: "string" },
+ "superseded-by": { type: "string" },
+ agent: { type: "string" },
+ json: { type: "boolean" },
+ });
+ if (positional.length < 1) return usageError("brain signal retire requires an <id> argument");
+ const reason = normalizeFlagString(flags["reason"]);
+ if (reason === null) return usageError("brain signal retire requires --reason <text>");
+ const supersededBy = normalizeFlagString(flags["superseded-by"]);
+ const { config, vault } = brainVerbContext(flags);
+ const agent = resolveBrainAgent(flags, config);
+ try {
+ const res = retireSignal(vault, positional[0]!, {
+ reason,
+ agent,
+ now: new Date(),
+ ...(supersededBy !== null ? { superseded_by: supersededBy } : {}),
+ });
+ if (flags["json"]) {
+ okJson({
+ id: res.id,
+ path: res.path,
+ status: "retired",
+ reason,
+ ...(supersededBy !== null ? { superseded_by: supersededBy } : {}),
+ });
+ } else {
+ ok(`retired: ${res.id}`);
+ }
+ return 0;
+ } catch (exc) {
+ if (
+ exc instanceof SignalNotFoundError ||
+ exc instanceof SignalAlreadyRetiredError ||
+ exc instanceof InvalidSignalIdError
+ ) {
+ process.stderr.write(`${exc.message}\n`);
+ return 2;
+ }
+ const message = `brain signal retire failed: ${(exc as Error).message}`;
+ if (flags["json"]) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
diff --git a/src/core/brain/atomic-facts.ts b/src/core/brain/atomic-facts.ts
index fd6f0492..d3a5939c 100644
--- a/src/core/brain/atomic-facts.ts
+++ b/src/core/brain/atomic-facts.ts
@@ -10,7 +10,7 @@
* missed one costs nothing.
*/
-import { normalizeEntityName } from "./entities/canonical.ts";
+import { entityMatchForms, normalizeEntityName } from "./entities/canonical.ts";
/** Cap on one assertion's text length. */
export const MAX_ASSERTION_CHARS = 300;
@@ -110,15 +110,26 @@ export function splitSentences(text: string): string[] {
return out.map((s) => s.trim()).filter((s) => s !== "");
}
-/** Anchor an assertion against active registry entities, sorted ids. */
+/** Minimum normalised form length that participates in substring matching. */
+const MIN_ANCHOR_FORM_LENGTH = 3;
+
+/**
+ * Anchor an assertion against active registry entities, sorted ids. Labels
+ * pass through the quality gate (sanitise decoration, then normalise, drop
+ * structurally-invalid forms) before matching - the same shared kernel the
+ * fact-extract path uses. Pure: no I/O, so a junk stored label is simply
+ * skipped (the fact-extract path is the one that logs the skip).
+ */
function anchorEntities(text: string, entities: ReadonlyArray<AtomicEntityLike>): string[] {
if (entities.length === 0) return [];
const haystack = normalizeEntityName(text);
const ids: string[] = [];
for (const entity of entities) {
if (entity.status !== "active") continue;
- const forms = [entity.name, ...entity.aliases].map((f) => normalizeEntityName(f));
- if (forms.some((f) => f.length >= 3 && haystack.includes(f))) ids.push(entity.id);
+ const forms = entityMatchForms([entity.name, ...entity.aliases]).filter(
+ (f) => f.length >= MIN_ANCHOR_FORM_LENGTH,
+ );
+ if (forms.some((f) => haystack.includes(f))) ids.push(entity.id);
}
return ids.toSorted();
}
diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.ts
index 9f9bd198..f1d90e6f 100644
--- a/src/core/brain/doctor.ts
+++ b/src/core/brain/doctor.ts
@@ -39,6 +39,7 @@
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative } from "node:path";
+import { realpathInsideVault, vaultRelative } from "../path-safety.ts";
import { REMOVED_TOOLS } from "../removed-surfaces.ts";
import { extractWikilinks, listVaultBasenames, parseFrontmatter } from "../vault.ts";
import { computeActiveBudgetPressure } from "./active-budget-pressure.ts";
@@ -49,6 +50,7 @@ import {
entityLexicalAliasCandidates,
resolveEntitySemanticDedupConfig,
} from "./entities/semantic-dedup.ts";
+import { findMalformedEntityLabels } from "./entities/label-hygiene.ts";
import { buildCaptureBoundary } from "./capture-boundary.ts";
import { verifyContentHash } from "./content-hash.ts";
import { readTierDriftCount } from "./frontmatter-tiers.ts";
@@ -398,6 +400,15 @@ export function runDoctor(vault: string, opts: RunDoctorOptions = {}): RunDoctor
} catch {
/* doctor never throws */
}
+ // Store hardening (D2): a symlink inside Brain/ whose realpath resolves
+ // OUTSIDE the vault root is an exfiltration/clobber hazard. Lint only -
+ // never auto-fixed, because removing an operator-created link is a
+ // judgment call.
+ try {
+ checkSymlinkEscape(vault, issues);
+ } catch {
+ /* doctor never throws */
+ }
// v0.14.0 semantic-health pass. Best-effort like every other lint:
// a failure here must not poison the structural warning / error
@@ -818,6 +829,46 @@ function checkLogs(vault: string, issues: DoctorIssue[]): void {
}
}
+// ----- Symlink-escape lint (D2) ---------------------------------------------
+
+/**
+ * Walk `Brain/` and report every symlink whose realpath resolves outside
+ * the vault root. Reuses {@link realpathInsideVault} (the same two-step
+ * check `ensureInsideVault` performs) so a symlink pointing at an
+ * in-vault target never flags. Directory symlinks are reported but NOT
+ * descended into - following them would leave the vault.
+ */
+function checkSymlinkEscape(vault: string, issues: DoctorIssue[]): void {
+ const root = brainDirs(vault).brain;
+ if (!existsSync(root)) return;
+ const visit = (dir: string): void => {
+ let entries;
+ try {
+ entries = readdirSync(dir, { withFileTypes: true });
+ } catch {
+ return;
+ }
+ for (const entry of entries) {
+ const full = join(dir, entry.name);
+ if (entry.isSymbolicLink()) {
+ if (!realpathInsideVault(full, vault)) {
+ issues.push({
+ severity: "error",
+ code: "symlink-escape",
+ path: vaultRelative(full, vault),
+ message:
+ `symlink '${vaultRelative(full, vault)}' resolves outside the vault root. ` +
+ "A reader following it leaves the vault; remove or repoint the link.",
+ });
+ }
+ continue; // never descend through a symlink
+ }
+ if (entry.isDirectory()) visit(full);
+ }
+ };
+ visit(root);
+}
+
// ----- Helpers --------------------------------------------------------------
function registerId(idIndex: Map<string, string[]>, id: string, path: string): void {
@@ -1358,6 +1409,22 @@ function checkEntities(vault: string, issues: DoctorIssue[]): void {
}
}
+ // A1 (t_657b365e): surface stored nodes whose labels fail the quality
+ // gate (structurally junk after decoration stripping, or operator-
+ // denylisted) as prune candidates. Warning severity - the operator runs
+ // `o2b brain entity prune` (dry-run default) to review and remove them.
+ for (const malformed of findMalformedEntityLabels(vault)) {
+ issues.push({
+ severity: "warning",
+ code: "entity-label-malformed",
+ path: malformed.path,
+ message:
+ `${malformed.id} has a malformed label ${JSON.stringify(malformed.name)} ` +
+ `(${malformed.reason}). Review with 'o2b brain entity prune' and re-run with ` +
+ "--confirm to remove the node and its edges behind a snapshot.",
+ });
+ }
+
// semantic-retrieval-precision (t_47fd9523): opt-in, proposal-only
// alias-merge candidates. Off by default → this block is a no-op and
// the report is byte-identical to the baseline. The doctor is
diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.ts
index 32392155..08ec4a96 100644
--- a/src/core/brain/dream.ts
+++ b/src/core/brain/dream.ts
@@ -63,7 +63,7 @@ import {
vaultRelative,
} from "./paths.ts";
import { countSigns, dominantSignOf } from "./sign.ts";
-import { isoDate, isoSecond } from "./time.ts";
+import { compactRunStamp, isoDate, isoSecond } from "./time.ts";
import {
emptyPlan,
filterWithinWindow,
@@ -1464,13 +1464,7 @@ function daysBetween(thenMs: number, nowMs: number): number {
function formatRunId(d: Date): string {
// dream-YYYY-MM-DD-HHMMSS
- const yyyy = d.getUTCFullYear().toString().padStart(4, "0");
- const mm = (d.getUTCMonth() + 1).toString().padStart(2, "0");
- const dd = d.getUTCDate().toString().padStart(2, "0");
- const hh = d.getUTCHours().toString().padStart(2, "0");
- const mi = d.getUTCMinutes().toString().padStart(2, "0");
- const ss = d.getUTCSeconds().toString().padStart(2, "0");
- return `dream-${yyyy}-${mm}-${dd}-${hh}${mi}${ss}`;
+ return `dream-${compactRunStamp(d)}`;
}
function nextAvailableDreamRunId(vault: string, baseRunId: string): string {
diff --git a/src/core/brain/entities/canonical.ts b/src/core/brain/entities/canonical.ts
index 6c1ded30..95c49409 100644
--- a/src/core/brain/entities/canonical.ts
+++ b/src/core/brain/entities/canonical.ts
@@ -36,3 +36,179 @@ export function validateEntityCategory(raw: string): string {
export function entityIdentityKey(category: string, name: string): string {
return `${validateEntityCategory(category)}:${normalizeEntityName(name)}`;
}
+
+// ----- Label quality gate (A1 / t_657b365e) ---------------------------------
+//
+// `normalizeEntityName` above stays byte-stable: it is the identity kernel
+// and its output feeds `entityIdentityKey`, so every currently-valid clean
+// label must key identically to before. The label QUALITY pass lives here as
+// a separate step applied BEFORE `normalizeEntityName` at every label-intake
+// boundary (entity creation, fact-extract anchoring, atomic-facts anchoring):
+// it strips Markdown decoration and surrounding punctuation, then rejects
+// structurally-junk labels. Junk detection is STRUCTURAL only (Unicode
+// property classes, never a natural-language word list); the sole vocabulary
+// source is the operator-supplied denylist threaded in by the caller.
+
+/**
+ * Upper bound on a sanitized label's length. A defensible ceiling: real
+ * entity names are short, and anything past this is a pasted blob, not a
+ * label. Exported so callers and tests share one source of truth.
+ */
+export const ENTITY_LABEL_MAX_LENGTH = 200;
+
+/** Leading Markdown heading marker: one-to-six `#` then required space/tab. */
+const HEADING_PREFIX_RE = /^#{1,6}[ \t]+/;
+
+/**
+ * Matched Markdown emphasis/code wrappers, longest opener first so `**`
+ * is peeled before `*`. One matched pair is removed per sanitise pass;
+ * the outer loop re-runs until the label stops changing.
+ */
+const EMPHASIS_WRAPPERS: ReadonlyArray<readonly [string, string]> = [
+ ["**", "**"],
+ ["__", "__"],
+ ["*", "*"],
+ ["_", "_"],
+ ["`", "`"],
+] as const;
+
+/** A leading run of Unicode punctuation (surrounding, not internal). */
+const LEADING_PUNCT_RE = /^\p{P}+/u;
+/** A trailing run of Unicode punctuation (surrounding, not internal). */
+const TRAILING_PUNCT_RE = /\p{P}+$/u;
+/** At least one letter or digit in ANY script - the "carries meaning" test. */
+const HAS_LETTER_OR_DIGIT_RE = /[\p{L}\p{N}]/u;
+
+/** Peel one matched emphasis/code wrapper pair, if present. */
+function stripSurroundingEmphasis(s: string): string {
+ for (const [open, close] of EMPHASIS_WRAPPERS) {
+ if (s.length >= open.length + close.length + 1 && s.startsWith(open) && s.endsWith(close)) {
+ return s.slice(open.length, s.length - close.length).trim();
+ }
+ }
+ return s;
+}
+
+/**
+ * Strip surrounding Markdown emphasis/heading decoration and surrounding
+ * (never internal) punctuation from a raw label, iterating until stable.
+ *
+ * Examples: `**Foo**` -> `Foo`, `# Heading` -> `Heading`, `_bar_` -> `bar`,
+ * `(baz)` -> `baz`, `Foo.` -> `Foo`. Internal punctuation is preserved, so
+ * `Node.js`, `e.g`, and `C++` survive. NFC-normalises and trims first so a
+ * clean label (`Ada`, `Open Second Brain`, `café`, `Ада`) is returned
+ * byte-identical to `raw.trim()` - the backward-compatibility guarantee for
+ * every currently-clean label.
+ */
+export function sanitizeEntityLabel(raw: string): string {
+ let s = raw.normalize("NFC").trim();
+ let prev = "";
+ while (s !== prev) {
+ prev = s;
+ s = s.replace(HEADING_PREFIX_RE, "").trim();
+ s = stripSurroundingEmphasis(s);
+ s = s.replace(LEADING_PUNCT_RE, "").replace(TRAILING_PUNCT_RE, "").trim();
+ }
+ return s;
+}
+
+/** Why a label was rejected by {@link validateEntityLabel}. */
+export type EntityLabelInvalidReason = "empty" | "too-long" | "no-letter-or-digit" | "denylisted";
+
+export interface EntityLabelValidation {
+ readonly valid: boolean;
+ readonly reason?: EntityLabelInvalidReason;
+}
+
+export interface ValidateEntityLabelOptions {
+ /**
+ * Operator-supplied denylist of exact labels, ALREADY normalised via
+ * `normalizeEntityName` (the comparison is post-normalization). The only
+ * vocabulary source; empty/absent means no name-based rejection.
+ */
+ readonly denylist?: ReadonlySet<string>;
+}
+
+/**
+ * Validate an already-sanitized label. Structural rejections only, plus the
+ * operator denylist:
+ * - `empty` - nothing survived sanitisation;
+ * - `too-long` - exceeds {@link ENTITY_LABEL_MAX_LENGTH};
+ * - `no-letter-or-digit` - no `\p{L}`/`\p{N}` in any script (pure
+ * punctuation/symbols);
+ * - `denylisted` - normalised form is in the operator denylist.
+ *
+ * The single source of truth for label validity - creation (typed error),
+ * anchoring (logged skip), doctor, and prune all route through it.
+ */
+export function validateEntityLabel(
+ sanitized: string,
+ opts: ValidateEntityLabelOptions = {},
+): EntityLabelValidation {
+ if (sanitized.length === 0) return { valid: false, reason: "empty" };
+ if (sanitized.length > ENTITY_LABEL_MAX_LENGTH) return { valid: false, reason: "too-long" };
+ if (!HAS_LETTER_OR_DIGIT_RE.test(sanitized))
+ return { valid: false, reason: "no-letter-or-digit" };
+ if (opts.denylist && opts.denylist.has(normalizeEntityName(sanitized))) {
+ return { valid: false, reason: "denylisted" };
+ }
+ return { valid: true };
+}
+
+/** Convenience boolean wrapper over {@link validateEntityLabel}. */
+export function isValidEntityLabel(
+ sanitized: string,
+ opts: ValidateEntityLabelOptions = {},
+): boolean {
+ return validateEntityLabel(sanitized, opts).valid;
+}
+
+/** Typed error raised when a label is rejected at a creation boundary. */
+export class InvalidEntityLabelError extends Error {
+ readonly reason: EntityLabelInvalidReason;
+ readonly raw: string;
+ readonly sanitized: string;
+ constructor(raw: string, sanitized: string, reason: EntityLabelInvalidReason) {
+ super(
+ `invalid entity label ${JSON.stringify(raw)} (${reason}): ` +
+ `sanitised form ${JSON.stringify(sanitized)} does not pass the label quality gate`,
+ );
+ this.name = "InvalidEntityLabelError";
+ this.reason = reason;
+ this.raw = raw;
+ this.sanitized = sanitized;
+ }
+}
+
+/**
+ * Sanitise `raw` and assert it passes the quality gate, returning the
+ * sanitized label for storage. Throws {@link InvalidEntityLabelError} on
+ * rejection - the creation-boundary contract (no silent drop).
+ */
+export function assertValidEntityLabel(raw: string, opts: ValidateEntityLabelOptions = {}): string {
+ const sanitized = sanitizeEntityLabel(raw);
+ const verdict = validateEntityLabel(sanitized, opts);
+ if (!verdict.valid) {
+ throw new InvalidEntityLabelError(raw, sanitized, verdict.reason!);
+ }
+ return sanitized;
+}
+
+/**
+ * Normalised match forms for an entity's labels (name + aliases): sanitise
+ * each, drop the structurally-invalid ones, then normalise the survivors.
+ * The shared anchoring kernel so fact-extract and atomic-facts compare
+ * facts against clean, valid label forms only. Pure - no I/O, no logging.
+ */
+export function entityMatchForms(
+ rawForms: ReadonlyArray<string>,
+ opts: ValidateEntityLabelOptions = {},
+): string[] {
+ const out: string[] = [];
+ for (const raw of rawForms) {
+ const sanitized = sanitizeEntityLabel(raw);
+ if (!isValidEntityLabel(sanitized, opts)) continue;
+ out.push(normalizeEntityName(sanitized));
+ }
+ return out;
+}
diff --git a/src/core/brain/entities/label-hygiene.ts b/src/core/brain/entities/label-hygiene.ts
new file mode 100644
index 00000000..54cab210
--- /dev/null
+++ b/src/core/brain/entities/label-hygiene.ts
@@ -0,0 +1,240 @@
+/**
+ * Entity-label hygiene: config-backed denylist resolution, malformed-node
+ * detection, and the snapshot-gated prune (A1 / t_657b365e).
+ *
+ * The pure label-quality primitives live in `canonical.ts`; this module is
+ * the I/O-aware layer around them. It resolves the operator denylist from the
+ * plugin config, re-runs the SAME validator over stored entity nodes to find
+ * historical junk labels (surfaced by the doctor and the prune dry-run), and
+ * removes failing nodes plus their inbound relation edges behind the shared
+ * D1 destructive-snapshot gate so a bad run is always recoverable.
+ */
+
+import { rmSync } from "node:fs";
+
+import { discoverConfig } from "../../config.ts";
+import type { FrontmatterMap } from "../../types.ts";
+import { parseFrontmatter, writeFrontmatterAtomic } from "../../vault.ts";
+import { normalizeRelationTarget } from "../../graph/frontmatter-relations.ts";
+import { relationFromFrontmatterField } from "../../graph/relation-vocab.ts";
+import { withDestructiveSnapshot } from "../snapshot-gate.ts";
+import {
+ normalizeEntityName,
+ sanitizeEntityLabel,
+ validateEntityLabel,
+ type EntityLabelInvalidReason,
+} from "./canonical.ts";
+import { buildEntityIndex, type EntityIndex } from "./index-builder.ts";
+import type { BrainEntity } from "./types.ts";
+
+/** Snapshot run-id label for a confirmed entity-label prune. */
+export const ENTITY_PRUNE_SNAPSHOT_LABEL = "entity-prune";
+
+/** Config key / env twin for the operator-supplied exact-label denylist. */
+export const ENTITY_LABEL_DENYLIST_CONFIG_KEY = "entities.label_denylist";
+export const ENTITY_LABEL_DENYLIST_ENV_KEY = "OPEN_SECOND_BRAIN_ENTITIES_LABEL_DENYLIST";
+
+/**
+ * Resolve the operator label denylist (env wins over config file). The raw
+ * value is a comma-separated list of EXACT labels; each entry is compared
+ * post-`normalizeEntityName`, so the returned set holds normalised forms.
+ * Empty / absent yields an empty set - the default is no name-based rejection.
+ */
+export function resolveEntityLabelDenylist(configPath?: string): ReadonlySet<string> {
+ const env = process.env[ENTITY_LABEL_DENYLIST_ENV_KEY];
+ const raw =
+ env !== undefined && env !== ""
+ ? env
+ : discoverConfig(configPath).data[ENTITY_LABEL_DENYLIST_CONFIG_KEY];
+ const out = new Set<string>();
+ if (!raw) return out;
+ for (const part of raw.split(",")) {
+ const normalized = normalizeEntityName(part);
+ if (normalized) out.add(normalized);
+ }
+ return out;
+}
+
+/** A stored entity whose label fails the quality gate - a prune candidate. */
+export interface MalformedEntityLabel {
+ readonly id: string;
+ readonly path: string;
+ readonly category: string;
+ /** The stored (unsanitised) display name. */
+ readonly name: string;
+ readonly status: string;
+ readonly reason: EntityLabelInvalidReason;
+ /** Ids of other entities that declare a relation edge pointing at this node. */
+ readonly inboundReferences: ReadonlyArray<string>;
+}
+
+/** Build the id -> [referrer id] map for inbound relation edges. */
+function inboundReferenceIndex(index: EntityIndex): Map<string, string[]> {
+ const inbound = new Map<string, string[]>();
+ for (const entity of index.entities) {
+ for (const edge of entity.relations) {
+ const list = inbound.get(edge.target);
+ if (list) {
+ if (!list.includes(entity.id)) list.push(entity.id);
+ } else {
+ inbound.set(edge.target, [entity.id]);
+ }
+ }
+ }
+ return inbound;
+}
+
+/**
+ * Re-run the label validator over every stored entity node (any status) and
+ * return the failing ones as prune candidates. Uses the SAME validator as
+ * creation and anchoring - one source of truth.
+ */
+export function findMalformedEntityLabels(
+ vault: string,
+ opts: { readonly denylist?: ReadonlySet<string>; readonly configPath?: string } = {},
+): MalformedEntityLabel[] {
+ const denylist = opts.denylist ?? resolveEntityLabelDenylist(opts.configPath);
+ const index = buildEntityIndex(vault);
+ const inbound = inboundReferenceIndex(index);
+ const out: MalformedEntityLabel[] = [];
+ for (const entity of index.entities) {
+ const verdict = validateEntityLabel(sanitizeEntityLabel(entity.name), { denylist });
+ if (verdict.valid) continue;
+ out.push(
+ Object.freeze({
+ id: entity.id,
+ path: entity.path,
+ category: entity.category,
+ name: entity.name,
+ status: entity.status,
+ reason: verdict.reason!,
+ inboundReferences: Object.freeze([...(inbound.get(entity.id) ?? [])]),
+ }),
+ );
+ }
+ return out;
+}
+
+export interface PruneEntityLabelsOptions {
+ /** Apply the removals. Absent / false is a dry run that mutates nothing. */
+ readonly confirm?: boolean;
+ /** Injected clock for a deterministic snapshot run id. */
+ readonly now?: Date;
+ readonly configPath?: string;
+ readonly denylist?: ReadonlySet<string>;
+}
+
+export interface PruneEntityLabelsResult {
+ readonly confirmed: boolean;
+ /** Malformed nodes found (the dry-run list; the confirm removal set). */
+ readonly candidates: ReadonlyArray<MalformedEntityLabel>;
+ /** Absolute paths of the node files removed (confirm only). */
+ readonly removed: ReadonlyArray<string>;
+ /** Count of inbound relation edges stripped from surviving nodes. */
+ readonly edgesStripped: number;
+ /** Recovery point taken behind the D1 gate, when work was applied. */
+ readonly snapshotRunId: string | null;
+ readonly snapshotPath: string | null;
+}
+
+/** One planned rewrite of a surviving node whose relations lost a target. */
+interface EdgeRewrite {
+ readonly path: string;
+ readonly meta: FrontmatterMap;
+ readonly body: string;
+ readonly removed: number;
+}
+
+/**
+ * Plan the inbound-edge removals: for every surviving entity, drop relation
+ * targets that resolve to a pruned id so no dangling `broken-entity-relation`
+ * survives the prune. Returns one rewrite per changed file plus the total
+ * number of edges removed.
+ */
+function planEdgeRewrites(
+ survivors: ReadonlyArray<BrainEntity>,
+ prunedIds: ReadonlySet<string>,
+): { rewrites: EdgeRewrite[]; edgesStripped: number } {
+ const rewrites: EdgeRewrite[] = [];
+ let edgesStripped = 0;
+ for (const entity of survivors) {
+ const [meta, body] = parseFrontmatter(entity.path);
+ let changed = 0;
+ const nextMeta: FrontmatterMap = {};
+ for (const [key, value] of Object.entries(meta)) {
+ if (!relationFromFrontmatterField(key)) {
+ nextMeta[key] = value;
+ continue;
+ }
+ const items = Array.isArray(value) ? value : value === "" ? [] : [value];
+ const kept = items.filter((item) => {
+ const target = normalizeRelationTarget(String(item));
+ if (target !== null && prunedIds.has(target)) {
+ changed++;
+ return false;
+ }
+ return true;
+ });
+ // Drop the relation key entirely when nothing remains, rather than
+ // leaving an empty `related: []` behind.
+ if (kept.length > 0) nextMeta[key] = kept;
+ }
+ if (changed > 0) {
+ edgesStripped += changed;
+ rewrites.push({ path: entity.path, meta: nextMeta, body, removed: changed });
+ }
+ }
+ return { rewrites, edgesStripped };
+}
+
+/**
+ * Prune stored entity nodes whose labels fail the quality gate. Dry-run by
+ * default (mutates nothing); `confirm: true` removes the node files AND
+ * strips inbound relation edges pointing at them, all inside a single
+ * pre-operation snapshot so the run is recoverable and leaves no orphaned
+ * references behind.
+ */
+export function pruneEntityLabels(
+ vault: string,
+ opts: PruneEntityLabelsOptions = {},
+): PruneEntityLabelsResult {
+ const denylist = opts.denylist ?? resolveEntityLabelDenylist(opts.configPath);
+ const candidates = findMalformedEntityLabels(vault, { denylist });
+
+ if (!opts.confirm || candidates.length === 0) {
+ return Object.freeze({
+ confirmed: false,
+ candidates: Object.freeze(candidates),
+ removed: Object.freeze([]),
+ edgesStripped: 0,
+ snapshotRunId: null,
+ snapshotPath: null,
+ });
+ }
+
+ const prunedIds = new Set(candidates.map((c) => c.id));
+ const prunePaths = candidates.map((c) => c.path);
+ const survivors = buildEntityIndex(vault).entities.filter((e) => !prunedIds.has(e.id));
+ const { rewrites, edgesStripped } = planEdgeRewrites(survivors, prunedIds);
+
+ const gated = withDestructiveSnapshot(
+ vault,
+ ENTITY_PRUNE_SNAPSHOT_LABEL,
+ () => {
+ for (const path of prunePaths) rmSync(path, { force: true });
+ for (const rewrite of rewrites) {
+ writeFrontmatterAtomic(rewrite.path, rewrite.meta, rewrite.body, { overwrite: true });
+ }
+ },
+ opts.now !== undefined ? { now: opts.now } : {},
+ );
+
+ return Object.freeze({
+ confirmed: true,
+ candidates: Object.freeze(candidates),
+ removed: Object.freeze([...prunePaths]),
+ edgesStripped,
+ snapshotRunId: gated.snapshot.runId,
+ snapshotPath: gated.snapshot.path,
+ });
+}
diff --git a/src/core/brain/entities/registry.ts b/src/core/brain/entities/registry.ts
index f5b7e90c..602c7b52 100644
--- a/src/core/brain/entities/registry.ts
+++ b/src/core/brain/entities/registry.ts
@@ -20,7 +20,13 @@ import { isKnownRelation, normalizeRelation } from "../../graph/relation-vocab.t
import { normalizeRelationTarget } from "../../graph/frontmatter-relations.ts";
import { isoSecond } from "../time.ts";
import { entityPath } from "../paths.ts";
-import { entityIdentityKey, normalizeEntityName, validateEntityCategory } from "./canonical.ts";
+import {
+ assertValidEntityLabel,
+ entityIdentityKey,
+ normalizeEntityName,
+ validateEntityCategory,
+} from "./canonical.ts";
+import { resolveEntityLabelDenylist } from "./label-hygiene.ts";
import { buildEntityIndex, parseEntityFile, type EntityIndex } from "./index-builder.ts";
import {
BRAIN_ENTITY_ID_PREFIX,
@@ -43,6 +49,8 @@ export interface UpsertEntityInput {
readonly confidence?: string;
/** Markdown body (current structured state). Replaces on update. */
readonly body?: string;
+ /** Config path for denylist resolution; env still wins when set. */
+ readonly configPath?: string;
}
export interface UpsertEntityResult {
@@ -212,8 +220,13 @@ function allocateEntityId(index: EntityIndex, category: string, name: string): s
export function upsertEntity(vault: string, input: UpsertEntityInput): UpsertEntityResult {
const category = validateEntityCategory(input.category);
- const name = input.name.trim();
- if (!normalizeEntityName(name)) throw new Error("entity name must not be empty");
+ // Label quality gate (A1): strip Markdown/punctuation decoration BEFORE
+ // normalisation and reject structurally-junk or denylisted names with a
+ // typed error at this creation boundary. The stored display name is the
+ // sanitised form; for a clean label sanitisation is a no-op, so the
+ // identity key stays byte-identical to before (backward compatibility).
+ const denylist = resolveEntityLabelDenylist(input.configPath);
+ const name = assertValidEntityLabel(input.name, { denylist });
const index = buildEntityIndex(vault);
const stamp = isoSecond(input.now);
diff --git a/src/core/brain/fact-extract.ts b/src/core/brain/fact-extract.ts
index a17a7647..d25a9d9c 100644
--- a/src/core/brain/fact-extract.ts
+++ b/src/core/brain/fact-extract.ts
@@ -26,11 +26,21 @@
import { createHash } from "node:crypto";
import { writeSignal } from "./signal.ts";
+import { appendLogEvent } from "./log.ts";
import { isoDate, isoSecond } from "./time.ts";
-import { BRAIN_SIGNAL_SOURCE_TYPE } from "./types.ts";
+import { BRAIN_LOG_EVENT_KIND, BRAIN_SIGNAL_SOURCE_TYPE } from "./types.ts";
+import { sanitiseTextField } from "../redactor.ts";
+import { classifyDurability, resolveDurabilityDenylist } from "./gates/durability.ts";
+import { resolveWriteApprovalEnabled } from "./pending.ts";
+import { brainDirs } from "./paths.ts";
import type { DedupIndexEntry } from "./dedup-hash.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
-import { normalizeEntityName } from "./entities/canonical.ts";
+import {
+ entityMatchForms,
+ normalizeEntityName,
+ sanitizeEntityLabel,
+ validateEntityLabel,
+} from "./entities/canonical.ts";
import { BRAIN_ENTITY_STATUS } from "./entities/types.ts";
export type FactFamily = "url" | "email" | "quantity";
@@ -188,27 +198,101 @@ export interface RouteFactsInput {
/** Shared dedup index (the caller owns it across turns/files). */
readonly dedup: Map<string, DedupIndexEntry>;
readonly dryRun?: boolean;
+ /**
+ * Pre-compiled operator durability denylist (A2). When omitted the router
+ * resolves `durability.denylist` from the plugin config on the first
+ * non-dry write; tests inject a compiled list directly so the wiring is
+ * exercised without touching the default config path.
+ */
+ readonly durabilityDenylist?: ReadonlyArray<RegExp>;
+ /**
+ * Write-approval toggle (A3). When omitted the router resolves
+ * `write_approval.enabled` from the plugin config on a non-dry write;
+ * tests inject the boolean directly. Enabled -> the durable signal is
+ * STAGED into `Brain/pending/`; disabled -> it lands in `Brain/inbox/`
+ * exactly as before (byte-for-byte).
+ */
+ readonly writeApprovalEnabled?: boolean;
}
export interface RouteFactsResult {
readonly created: number;
readonly deduped: number;
+ /**
+ * Facts the durability gate (A2) rejected as transient operational
+ * content before the write. Each rejection is also a logged
+ * `durability-skip` event - this count is the additive result-shape
+ * surface, never a silent drop.
+ */
+ readonly durabilityRejected: number;
+}
+
+/** Max length of the redacted fact text carried onto a `durability-skip` log. */
+const DURABILITY_LOG_TEXT_MAX_LEN = 200;
+
+/** Minimum normalised form length that participates in substring matching. */
+const MIN_ANCHOR_FORM_LENGTH = 3;
+
+/** A registry entity reduced to its clean, matchable label forms. */
+interface AnchorableEntity {
+ readonly id: string;
+ readonly forms: ReadonlyArray<string>;
}
/**
- * Resolve canonical-entity anchors for a fact: every active registry
- * entity whose name or alias (normalised) appears in the fact text.
- * The canonicalization kernel is the comparison boundary, so facts and
- * the registry compare like with like.
+ * Reduce the active registry to anchorable entities: sanitise each label
+ * (name + aliases) through the quality gate before normalisation and keep
+ * only the valid forms. When the stored NAME fails the gate the skip is
+ * logged (via a dedicated event kind) and contained - a logging failure
+ * never aborts the enclosing capture, and `doctor` surfaces the same node
+ * as a prune candidate. The entity is still anchored on its remaining
+ * VALID forms (aliases that pass the gate): a node with at least one valid
+ * form is never silently excluded, matching the atomic-facts anchoring path.
*/
-function entityAnchors(index: ReturnType<typeof buildEntityIndex>, factText: string): string[] {
- if (index.entities.length === 0) return [];
- const haystack = normalizeEntityName(factText);
- const ids: string[] = [];
+function buildAnchorables(
+ vault: string,
+ index: ReturnType<typeof buildEntityIndex>,
+ agent: string,
+ now: Date,
+): AnchorableEntity[] {
+ const out: AnchorableEntity[] = [];
for (const entity of index.entities) {
if (entity.status !== BRAIN_ENTITY_STATUS.active) continue;
- const forms = [entity.name, ...entity.aliases].map((f) => normalizeEntityName(f));
- if (forms.some((f) => f.length >= 3 && haystack.includes(f))) ids.push(entity.id);
+ const nameVerdict = validateEntityLabel(sanitizeEntityLabel(entity.name));
+ if (!nameVerdict.valid) {
+ try {
+ appendLogEvent(vault, {
+ timestamp: isoSecond(now),
+ eventType: BRAIN_LOG_EVENT_KIND.entityAnchorSkip,
+ body: { entity: entity.id, name: entity.name, reason: nameVerdict.reason!, agent },
+ });
+ } catch {
+ // A skip that cannot be logged must still not break capture.
+ }
+ // Fall through: entityMatchForms drops the junk name form itself, so a
+ // valid alias still yields an anchorable form.
+ }
+ const forms = entityMatchForms([entity.name, ...entity.aliases]).filter(
+ (f) => f.length >= MIN_ANCHOR_FORM_LENGTH,
+ );
+ if (forms.length === 0) continue;
+ out.push({ id: entity.id, forms });
+ }
+ return out;
+}
+
+/**
+ * Resolve canonical-entity anchors for a fact: every anchorable registry
+ * entity whose normalised label form appears in the fact text. The
+ * canonicalization kernel is the comparison boundary, so facts and the
+ * registry compare like with like.
+ */
+function entityAnchors(anchorables: ReadonlyArray<AnchorableEntity>, factText: string): string[] {
+ if (anchorables.length === 0) return [];
+ const haystack = normalizeEntityName(factText);
+ const ids: string[] = [];
+ for (const entity of anchorables) {
+ if (entity.forms.some((f) => haystack.includes(f))) ids.push(entity.id);
}
return ids;
}
@@ -221,45 +305,114 @@ function entityAnchors(index: ReturnType<typeof buildEntityIndex>, factText: str
* the capture boundary; both seams pin that order with tests.
*/
export function routeExtractedFacts(vault: string, input: RouteFactsInput): RouteFactsResult {
- if (input.facts.length === 0) return { created: 0, deduped: 0 };
+ if (input.facts.length === 0) return { created: 0, deduped: 0, durabilityRejected: 0 };
let created = 0;
let deduped = 0;
+ let durabilityRejected = 0;
let entityIndex: ReturnType<typeof buildEntityIndex>;
try {
entityIndex = buildEntityIndex(vault);
} catch {
entityIndex = { entities: [], byKey: new Map(), byAlias: new Map(), conflicts: [] };
}
+ // Precompute anchorable entities once (a dry run writes nothing, so it
+ // neither anchors nor logs skips). Junk-label nodes are skipped-with-log here.
+ const anchorables = input.dryRun
+ ? []
+ : buildAnchorables(vault, entityIndex, input.agent, input.now);
+
+ // Resolve the operator durability denylist once (an injected list wins so
+ // tests exercise the wiring without the default config path). Tolerant: a
+ // bad config never crashes capture, and the built-in structural detectors
+ // remain the primary gate.
+ let durabilityDenylist: ReadonlyArray<RegExp> = input.durabilityDenylist ?? [];
+ if (input.durabilityDenylist === undefined && !input.dryRun) {
+ try {
+ durabilityDenylist = resolveDurabilityDenylist();
+ } catch {
+ durabilityDenylist = [];
+ }
+ }
+
+ // Staging decision (A3), resolved once AFTER the durability gate would run:
+ // an injected toggle wins (tests); otherwise the config decides. A durable
+ // signal is staged into Brain/pending/ when enabled, or written to
+ // Brain/inbox/ (targetDir undefined = byte-for-byte legacy path) when not.
+ let writeApprovalEnabled = input.writeApprovalEnabled ?? false;
+ if (input.writeApprovalEnabled === undefined && !input.dryRun) {
+ try {
+ writeApprovalEnabled = resolveWriteApprovalEnabled();
+ } catch {
+ writeApprovalEnabled = false;
+ }
+ }
+ const targetDir = writeApprovalEnabled ? brainDirs(vault).pending : undefined;
for (const fact of input.facts) {
const hash = factDedupHash(fact);
+ // Chain order: dedup -> durability -> staging -> write. A deduped item
+ // never reaches the durability gate.
if (input.dedup.has(hash)) {
deduped++;
continue;
}
+ // Durability gate (A2): reject transient operational content before the
+ // write. A rejected fact is a counted, logged skip - never a silent drop.
+ const verdict = classifyDurability(fact.text, { denylist: durabilityDenylist });
+ if (!verdict.durable) {
+ durabilityRejected++;
+ if (!input.dryRun) {
+ try {
+ appendLogEvent(vault, {
+ timestamp: isoSecond(input.now),
+ eventType: BRAIN_LOG_EVENT_KIND.durabilitySkip,
+ agent: input.agent,
+ body: {
+ family: fact.family,
+ reason: verdict.reason!,
+ // Secret-redacted for the LOG surface only (matching the
+ // attribute-write audit); the fact is skipped, not written.
+ text: sanitiseTextField(fact.text, {
+ maxLen: DURABILITY_LOG_TEXT_MAX_LEN,
+ singleLine: true,
+ }),
+ hash,
+ agent: input.agent,
+ },
+ });
+ } catch {
+ // A skip that cannot be logged must still not break capture.
+ }
+ }
+ continue;
+ }
if (input.dryRun) continue;
- const anchors = entityAnchors(entityIndex, fact.text);
+ const anchors = entityAnchors(anchorables, fact.text);
const topic = `fact-${fact.family}`;
try {
- const result = writeSignal(vault, {
- topic,
- signal: "positive",
- agent: input.agent,
- principle: fact.text,
- created_at: isoSecond(input.now),
- date: isoDate(input.now),
- slug: topic,
- source: [`[[${input.sessionRef}]]`],
- source_type: BRAIN_SIGNAL_SOURCE_TYPE.extracted,
- dedup_hash: hash,
- session_ref: input.sessionRef,
- ...(anchors.length > 0 ? { raw: `entities: ${anchors.join(", ")}` } : {}),
- });
+ const result = writeSignal(
+ vault,
+ {
+ topic,
+ signal: "positive",
+ agent: input.agent,
+ principle: fact.text,
+ created_at: isoSecond(input.now),
+ date: isoDate(input.now),
+ slug: topic,
+ source: [`[[${input.sessionRef}]]`],
+ source_type: BRAIN_SIGNAL_SOURCE_TYPE.extracted,
+ dedup_hash: hash,
+ session_ref: input.sessionRef,
+ ...(anchors.length > 0 ? { raw: `entities: ${anchors.join(", ")}` } : {}),
+ },
+ targetDir !== undefined ? { targetDir } : {},
+ );
input.dedup.set(hash, { id: result.id, path: result.path });
created++;
} catch {
// One unwritable fact must not break capture; the next turn retries.
}
}
- return { created, deduped };
+ return { created, deduped, durabilityRejected };
}
diff --git a/src/core/brain/gates/durability.ts b/src/core/brain/gates/durability.ts
new file mode 100644
index 00000000..cdbff56e
--- /dev/null
+++ b/src/core/brain/gates/durability.ts
@@ -0,0 +1,338 @@
+/**
+ * Deterministic durability gate (A2 / t_375e98fd).
+ *
+ * `classifyDurability(text)` decides whether an extracted fact is DURABLE
+ * (worth persisting) or TRANSIENT operational noise that should be skipped
+ * before it reaches the inbox. The decision is made from STRUCTURAL signals
+ * ONLY - there is deliberately zero built-in natural-language word list, in
+ * any language, so the gate behaves identically across scripts (a plain
+ * sentence in Russian, Japanese, Arabic, or English is durable unless it
+ * carries a structural transient shape).
+ *
+ * The allowed structural signal classes are:
+ * - `temp-path` filesystem temp paths (`/tmp/`, `*.tmp`, OS temp
+ * dir shapes, `%TEMP%`, `$TMPDIR`);
+ * - `progress-counter` `N/M` ratios and `NN%` percentages;
+ * - `run-id` run-id / timestamp-suffixed identifier shapes and
+ * ISO-8601 datetimes / long epoch numbers;
+ * - `measurement-dominant` measurement tokens (numbers with unit suffixes
+ * like `ms`, `s`, `MB`) as the dominant token class;
+ * - `exit-status` process exit-status shapes (POSIX `SIG*` signal
+ * identifiers, the shell `$?` status variable).
+ *
+ * The only vocabulary source is the OPERATOR-supplied `durability.denylist`
+ * config (a comma-separated list of regexes), threaded in through `opts`.
+ *
+ * `classifyDurability` and every detector are PURE and deterministic: same
+ * input, same verdict, no I/O. The config resolver `resolveDurabilityDenylist`
+ * is the one I/O-aware helper and is kept separate from the classifier.
+ */
+
+import { discoverConfig } from "../../config.ts";
+
+/** Named structural signal (or the operator denylist) that fired. */
+export type DurabilitySignal =
+ | "temp-path"
+ | "progress-counter"
+ | "run-id"
+ | "measurement-dominant"
+ | "exit-status"
+ | "denylisted";
+
+export interface DurabilityVerdict {
+ /** `true` when the text carries no transient signal - safe to persist. */
+ readonly durable: boolean;
+ /** The structural signal that rejected the text, or `null` when durable. */
+ readonly reason: DurabilitySignal | null;
+}
+
+export interface ClassifyDurabilityOptions {
+ /**
+ * Operator denylist regexes (already compiled through
+ * {@link compileDurabilityDenylist}). Non-global by construction so
+ * `.test` stays stateless and the classifier stays deterministic.
+ */
+ readonly denylist?: ReadonlyArray<RegExp>;
+}
+
+// ----- Detectors (each pure, individually tested) ---------------------------
+
+/**
+ * Filesystem temp-path shapes. Unix temp dirs (`/tmp`, `/var/tmp`,
+ * `/var/folders/...`), a `.tmp` file extension, a Windows `...\Temp\`
+ * segment, and the `%TEMP%` / `%TMP%` / `$TMPDIR` environment tokens. These
+ * are path SHAPES, not words: "temperature" or "attempts" never match.
+ */
+const TEMP_PATH_PATTERNS: ReadonlyArray<RegExp> = [
+ /(?:^|[\s"'(=:,])\/(?:tmp|var\/tmp|var\/folders)(?:\/|\b)/,
+ /\.tmp(?=$|[\s"')\]},.:;])/i,
+ /(?:^|[\\/])Temp[\\/]/,
+ /%(?:TEMP|TMP)%/i,
+ /\$TMPDIR\b/,
+];
+
+export function hasTempPath(text: string): boolean {
+ return TEMP_PATH_PATTERNS.some((re) => re.test(text));
+}
+
+/**
+ * Progress-counter tokens: an `N/M` integer ratio (e.g. `3/10`) or an
+ * `NN%` percentage (e.g. `87%`, `50%`). Both are language-neutral notation.
+ * Matched as WHOLE tokens (after stripping wrapper punctuation) so a
+ * counter is only detected when it stands on its own, not when the same
+ * notation is embedded in a factual sentence.
+ */
+const RATIO_TOKEN_RE = /^\d+\/\d+$/;
+const PERCENT_TOKEN_RE = /^\d+(?:\.\d+)?%$/;
+
+/** Minimum share of counter tokens for the "counter-dominant" verdict. */
+export const PROGRESS_COUNTER_DOMINANCE_MIN_SHARE = 0.25;
+
+/**
+ * True when progress-counter tokens are counter-DOMINANT: their share of
+ * whitespace-split tokens (after stripping wrapper punctuation, but never
+ * the meaningful `%`/`/`) meets {@link PROGRESS_COUNTER_DOMINANCE_MIN_SHARE}.
+ * A standalone `50%` or `3/10 done` status line is counter-dominant; a
+ * percentage embedded in prose (`Acme owns 50% of the venture`) is not, so
+ * a durable fact carrying incidental notation is not discarded as transient.
+ */
+export function hasProgressCounter(text: string): boolean {
+ const tokens = text.split(/\s+/).filter((t) => t.length > 0);
+ if (tokens.length === 0) return false;
+ let counters = 0;
+ for (const token of tokens) {
+ const stripped = token.replace(/^["'([{]+/, "").replace(/["')\]}.,:;!?]+$/, "");
+ if (RATIO_TOKEN_RE.test(stripped) || PERCENT_TOKEN_RE.test(stripped)) counters++;
+ }
+ return counters > 0 && counters / tokens.length >= PROGRESS_COUNTER_DOMINANCE_MIN_SHARE;
+}
+
+/**
+ * Run-id / timestamp shapes: an ISO-8601 datetime, an identifier suffixed
+ * with a long digit run (`run-20260718`, `job_1721304000`, `build-987654`),
+ * or a bare long (>= 10-digit) number - the shape of a unix epoch. A short
+ * number in prose ("version 3") never matches.
+ */
+const ISO_DATETIME_RE = /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2})?/;
+const IDENTIFIER_LONGNUM_RE = /[A-Za-z][A-Za-z0-9]*[-_]\d{6,}/;
+const LONG_EPOCH_RE = /\b\d{10,}\b/;
+
+export function hasRunIdShape(text: string): boolean {
+ return ISO_DATETIME_RE.test(text) || IDENTIFIER_LONGNUM_RE.test(text) || LONG_EPOCH_RE.test(text);
+}
+
+/**
+ * Measurement tokens: a number immediately followed by a technical unit
+ * suffix (durations, byte sizes, rates, screen units). The suffix must be
+ * attached to the number (`500ms`, not `500 ms`) so an ambiguous bare word
+ * ("s", "m") cannot match on its own. These are technical notation, not
+ * natural-language words.
+ */
+const MEASUREMENT_TOKEN_RE =
+ /^\d+(?:\.\d+)?(?:ns|us|µs|ms|s|m|h|d|B|KB|MB|GB|TB|PB|KiB|MiB|GiB|TiB|bps|kbps|Mbps|Gbps|Hz|kHz|MHz|GHz|fps|rpm|px|em|rem)$/i;
+
+/** Minimum share of measurement tokens for the "dominant class" verdict. */
+export const MEASUREMENT_DOMINANCE_MIN_SHARE = 0.5;
+
+/**
+ * True when measurement tokens are the DOMINANT token class: their share of
+ * whitespace-split tokens (after stripping surrounding punctuation) meets
+ * {@link MEASUREMENT_DOMINANCE_MIN_SHARE}. A single bare measurement
+ * (`500ms`) is dominant; a measurement buried in a prose sentence is not.
+ */
+export function hasMeasurementDominance(text: string): boolean {
+ const tokens = text.split(/\s+/).filter((t) => t.length > 0);
+ if (tokens.length === 0) return false;
+ let measurement = 0;
+ for (const token of tokens) {
+ const stripped = token.replace(/^[^\p{L}\p{N}]+/u, "").replace(/[^\p{L}\p{N}]+$/u, "");
+ if (MEASUREMENT_TOKEN_RE.test(stripped)) measurement++;
+ }
+ return measurement > 0 && measurement / tokens.length >= MEASUREMENT_DOMINANCE_MIN_SHARE;
+}
+
+/**
+ * Process exit-status shapes. POSIX signal identifiers (`SIGKILL`,
+ * `SIGTERM`, ...) are a standardized identifier namespace - a wire-protocol
+ * token family, not a natural-language word list, in the same spirit that
+ * ISO-4217 currency codes are treated as language-neutral notation
+ * elsewhere in this codebase. The shell `$?` status variable is likewise
+ * pure notation.
+ */
+const POSIX_SIGNAL_RE = /\bSIG[A-Z]{2,}\b/;
+const SHELL_STATUS_RE = /\$\?/;
+
+export function hasExitStatusShape(text: string): boolean {
+ return POSIX_SIGNAL_RE.test(text) || SHELL_STATUS_RE.test(text);
+}
+
+/**
+ * Ordered detector table. `classifyDurability` returns the reason of the
+ * FIRST detector that fires, so the order fixes which reason a text carrying
+ * several shapes is labelled with. Each entry is a named, individually-tested
+ * detector, so a new structural signal is added by appending one row - no
+ * monolith to edit.
+ */
+export const DURABILITY_DETECTORS: ReadonlyArray<
+ readonly [Exclude<DurabilitySignal, "denylisted">, (text: string) => boolean]
+> = [
+ ["temp-path", hasTempPath],
+ ["progress-counter", hasProgressCounter],
+ ["run-id", hasRunIdShape],
+ ["measurement-dominant", hasMeasurementDominance],
+ ["exit-status", hasExitStatusShape],
+];
+
+/**
+ * Classify a fact's text as durable or transient. Built-in structural
+ * detectors run first (in table order), then the operator denylist. Pure and
+ * deterministic - the property the property-test pins.
+ */
+export function classifyDurability(
+ text: string,
+ opts: ClassifyDurabilityOptions = {},
+): DurabilityVerdict {
+ if (text.trim().length === 0) return { durable: true, reason: null };
+ for (const [reason, detector] of DURABILITY_DETECTORS) {
+ if (detector(text)) return { durable: false, reason };
+ }
+ for (const re of opts.denylist ?? []) {
+ // Defensive reset: even though compileDurabilityDenylist strips the
+ // global/sticky flags, resetting lastIndex keeps a caller-supplied regex
+ // stateless so the verdict stays deterministic.
+ re.lastIndex = 0;
+ if (re.test(text)) return { durable: false, reason: "denylisted" };
+ }
+ return { durable: true, reason: null };
+}
+
+// ----- Operator denylist config (durability.denylist) -----------------------
+
+/** Config key / env twin for the operator-supplied durability denylist. */
+export const DURABILITY_DENYLIST_CONFIG_KEY = "durability.denylist";
+export const DURABILITY_DENYLIST_ENV_KEY = "OPEN_SECOND_BRAIN_DURABILITY_DENYLIST";
+
+/**
+ * True when the quantifier starting at index `i` of `source` is unbounded:
+ * `*`, `+`, or `{n,}` / `{,}` (no upper bound). `{n}` and `{n,m}` are bounded.
+ */
+function isUnboundedQuantifierAt(source: string, i: number): boolean {
+ const ch = source[i];
+ if (ch === "*" || ch === "+") return true;
+ if (ch === "{") {
+ const close = source.indexOf("}", i);
+ return close !== -1 && /^\d*,$/.test(source.slice(i + 1, close));
+ }
+ return false;
+}
+
+/** True when a group body carries an unbounded quantifier (ignores classes). */
+function bodyHasUnboundedQuantifier(body: string): boolean {
+ let inClass = false;
+ for (let i = 0; i < body.length; i++) {
+ const ch = body[i];
+ if (ch === "\\") {
+ i++;
+ continue;
+ }
+ if (inClass) {
+ if (ch === "]") inClass = false;
+ continue;
+ }
+ if (ch === "[") {
+ inClass = true;
+ continue;
+ }
+ if (isUnboundedQuantifierAt(body, i)) return true;
+ }
+ return false;
+}
+
+/**
+ * Reject a regex source that carries the classic catastrophic-backtracking
+ * shape: an unbounded quantifier (`*`, `+`, `{n,}`) applied to a group whose
+ * body ALSO contains an unbounded quantifier (`(a+)+`, `(.*)*`, `([0-9]+)*`).
+ * These patterns can stall {@link classifyDurability} - which runs the
+ * operator denylist synchronously on every fact - for exponential time on a
+ * crafted input. Bounded (`{n}`, `{n,m}`) quantifiers and single-level
+ * quantifiers (`(abc)+`) are safe and pass. This is a targeted guard for the
+ * dominant ReDoS class, not a complete safe-regex analyzer (alternation
+ * overlap such as `(a|a)+` is out of scope); it exists so an operator typo
+ * cannot turn the capture hot path into a denial of service.
+ */
+export function hasNestedUnboundedQuantifier(source: string): boolean {
+ const stack: number[] = [];
+ let inClass = false;
+ for (let i = 0; i < source.length; i++) {
+ const ch = source[i];
+ if (ch === "\\") {
+ i++;
+ continue;
+ }
+ if (inClass) {
+ if (ch === "]") inClass = false;
+ continue;
+ }
+ if (ch === "[") {
+ inClass = true;
+ continue;
+ }
+ if (ch === "(") {
+ stack.push(i);
+ continue;
+ }
+ if (ch === ")") {
+ const start = stack.pop();
+ if (start === undefined) continue;
+ if (
+ isUnboundedQuantifierAt(source, i + 1) &&
+ bodyHasUnboundedQuantifier(source.slice(start + 1, i))
+ ) {
+ return true;
+ }
+ }
+ }
+ return false;
+}
+
+/**
+ * Compile a comma-separated list of operator regexes into non-global
+ * `RegExp` objects. Pure. An unparseable OR catastrophic-backtracking entry
+ * is SKIPPED rather than thrown (the same tolerance `resolveTimezone` applies
+ * to an invalid IANA zone): an operator typo must never crash or stall the
+ * capture hot path, and the built-in structural detectors remain the primary
+ * gate. Empty / absent yields `[]`.
+ *
+ * Multiple patterns are comma-delimited; a regex that needs a literal comma
+ * can spell it `[,]` or `\x2c`, matching the exact-label denylist convention.
+ */
+export function compileDurabilityDenylist(raw: string | undefined): RegExp[] {
+ if (!raw) return [];
+ const out: RegExp[] = [];
+ for (const part of raw.split(",")) {
+ const pattern = part.trim();
+ if (pattern.length === 0) continue;
+ // Reject unsafe patterns before compiling: the denylist runs on every
+ // fact, so a catastrophic-backtracking regex is a denial-of-service.
+ if (hasNestedUnboundedQuantifier(pattern)) continue;
+ try {
+ out.push(new RegExp(pattern));
+ } catch {
+ // Skip the malformed pattern; capture must never break on bad config.
+ }
+ }
+ return out;
+}
+
+/**
+ * Resolve the operator denylist (env wins over config file), mirroring the
+ * A1 label-denylist resolver. I/O-aware; the pure classifier never calls it.
+ */
+export function resolveDurabilityDenylist(configPath?: string): RegExp[] {
+ const env = process.env[DURABILITY_DENYLIST_ENV_KEY];
+ const raw =
+ env !== undefined && env !== ""
+ ? env
+ : discoverConfig(configPath).data[DURABILITY_DENYLIST_CONFIG_KEY];
+ return compileDurabilityDenylist(raw);
+}
diff --git a/src/core/brain/health/contradiction.ts b/src/core/brain/health/contradiction.ts
index 613c7644..953ea1bd 100644
--- a/src/core/brain/health/contradiction.ts
+++ b/src/core/brain/health/contradiction.ts
@@ -15,7 +15,8 @@
*/
import { dominantSignOf } from "../sign.ts";
-import { findSimilarPairs, tokenise } from "../similarity.ts";
+import { findSimilarPairs, jaccard, tokenise } from "../similarity.ts";
+import { BRAIN_HEALTH_DEFAULTS } from "../policy.ts";
import {
BRAIN_PREFERENCE_STATUS,
type BrainPreferenceStatus,
@@ -240,6 +241,79 @@ export function detectNoteContradictions(
return out;
}
+/** Evidence for one incoming-vs-confirmed conflict. */
+export interface IncomingConflictEvidence {
+ /** The confirmed preference the incoming principle resembles. */
+ readonly prefId: string;
+ /** Principle-token jaccard that put the pair over the threshold. */
+ readonly jaccard: number;
+}
+
+/**
+ * A write-time conflict advisory: the confirmed same-scope preferences an
+ * incoming feedback principle resembles closely enough to be worth a
+ * second look. Advisory only - it is never a reason to block a write.
+ */
+export interface IncomingConflictAdvisory {
+ /** The scope bucket compared against; `null` for the unscoped bucket. */
+ readonly scope: string | null;
+ /** Non-empty, sorted by descending similarity then id. */
+ readonly conflicts: ReadonlyArray<IncomingConflictEvidence>;
+}
+
+export interface AdviseOnIncomingOptions {
+ /**
+ * Minimum principle jaccard for a confirmed preference to count as the
+ * same subject. Defaults to the health-pass default
+ * (`BRAIN_HEALTH_DEFAULTS.contradiction_jaccard`) so the write-time
+ * advisory and the batch contradiction detector use one threshold.
+ */
+ readonly jaccard?: number;
+}
+
+/**
+ * Compute a write-time conflict advisory for a single incoming feedback
+ * principle against already-confirmed preferences. Reuses the shared
+ * similarity kernel (`tokenise` + `jaccard`) that `detectContradictions`
+ * builds on, and mirrors its bucketing: only confirmed preferences in the
+ * SAME scope bucket are compared (an unscoped incoming signal compares
+ * against the unscoped bucket). Every confirmed same-scope preference
+ * whose principle overlaps the incoming principle at or above the
+ * threshold is returned as evidence.
+ *
+ * Unlike `detectContradictions`, this is a similarity-only signal: it does
+ * not derive preference polarity (that would require the full signal-sign
+ * map, which the write path deliberately does not load - only the scope
+ * bucket is read). High principle overlap is the language-agnostic shape
+ * of "you may be contradicting or duplicating an existing rule"; the
+ * operator judges. Pure and deterministic; never throws on well-formed
+ * input.
+ *
+ * Returns `null` when no confirmed same-scope preference clears the
+ * threshold - i.e. there is nothing to advise about.
+ */
+export function adviseOnIncoming(
+ principle: string,
+ scope: string | undefined,
+ confirmedPrefs: ReadonlyArray<PreferenceForContradiction>,
+ opts: AdviseOnIncomingOptions = {},
+): IncomingConflictAdvisory | null {
+ const threshold = opts.jaccard ?? BRAIN_HEALTH_DEFAULTS.contradiction_jaccard;
+ const bucketKey = scope ?? "";
+ const incomingTokens = tokenise(principle);
+ const conflicts: IncomingConflictEvidence[] = [];
+ for (const p of confirmedPrefs) {
+ if (p.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;
+ if ((p.scope ?? "") !== bucketKey) continue;
+ const sim = jaccard(incomingTokens, tokenise(p.principle));
+ if (sim < threshold) continue;
+ conflicts.push({ prefId: p.id, jaccard: sim });
+ }
+ if (conflicts.length === 0) return null;
+ conflicts.sort((a, b) => b.jaccard - a.jaccard || a.prefId.localeCompare(b.prefId));
+ return { scope: scope ?? null, conflicts };
+}
+
/**
* Detect contradictory confirmed-preference pairs. Preferences are
* bucketed by scope (so only same-scope rules are compared), paired by
diff --git a/src/core/brain/health/remediation.ts b/src/core/brain/health/remediation.ts
index d7dd07e3..844c25cf 100644
--- a/src/core/brain/health/remediation.ts
+++ b/src/core/brain/health/remediation.ts
@@ -18,9 +18,10 @@
* judgment).
*/
-import { existsSync, readdirSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
import { join } from "node:path";
+import { ensureInsideVault, vaultRelative } from "../../path-safety.ts";
import { parseFrontmatter, writeFrontmatterAtomic } from "../../vault.ts";
import { computeContentHash, verifyContentHash } from "../content-hash.ts";
import { brainDirs, preferencePath } from "../paths.ts";
@@ -30,6 +31,20 @@ import { BRAIN_PREFERENCE_STATUS } from "../types.ts";
export type RemediationClass = "auto-safe" | "needs-review";
+/** Canonical hardened modes: owner-only for files and directories. */
+const FILE_TARGET_MODE = 0o600;
+const DIR_TARGET_MODE = 0o700;
+/** Group + other permission bits. Any set = "wider than owner-only". */
+const NON_OWNER_MODE_MASK = 0o077;
+
+export interface WidePermissionFinding {
+ /** Vault-relative POSIX path of the over-permissioned entry. */
+ readonly path: string;
+ readonly isDir: boolean;
+ /** Current permission bits (`mode & 0o777`). */
+ readonly mode: number;
+}
+
export interface RemediationStep {
/** Finding code this step addresses. */
readonly code: string;
@@ -53,6 +68,11 @@ export interface RemediationFindings {
readonly contradictions: ReadonlyArray<{ aId: string; bId: string }>;
readonly staleClaims: ReadonlyArray<{ id: string }>;
readonly conceptGaps: ReadonlyArray<{ term: string }>;
+ /**
+ * Brain/ entries whose POSIX mode is wider than owner-only (D2). Optional
+ * so existing callers stay valid; absent is treated as an empty list.
+ */
+ readonly widePermissions?: ReadonlyArray<WidePermissionFinding>;
}
export interface PlanRemediationOptions {
@@ -75,10 +95,11 @@ export interface RemediationOutcome {
// review steps. Pinned explicitly so the plan is identical on every
// Syncthing peer.
const CODE_ORDER: ReadonlyMap<string, number> = new Map([
- ["content-hash-drift", 0],
- ["contradictory-preferences", 1],
- ["stale-claim", 2],
- ["concept-gap", 3],
+ ["wide-permissions", 0],
+ ["content-hash-drift", 1],
+ ["contradictory-preferences", 2],
+ ["stale-claim", 3],
+ ["concept-gap", 4],
]);
/**
@@ -114,12 +135,86 @@ export function collectDriftedSlugs(vault: string): string[] {
return out.toSorted((a, b) => a.localeCompare(b));
}
+export interface CollectWidePermissionsOptions {
+ /** Injectable platform for testing; defaults to `process.platform`. */
+ readonly platform?: NodeJS.Platform;
+ /** Injectable logger for the Windows skip line; defaults to stderr. */
+ readonly log?: (message: string) => void;
+}
+
+/**
+ * Scan `Brain/` for files/dirs whose POSIX mode exposes group/other
+ * permissions - the `harden-permissions` targets. Symlinks are skipped
+ * (a chmod would touch the link target, not the link).
+ *
+ * On Windows the walk is skipped entirely: POSIX file modes are not
+ * meaningful there. Per the no-silent-fallback rule this skip is logged
+ * with an explicit reason rather than returning an empty list quietly.
+ *
+ * Returns findings sorted by path for deterministic plans. Already-tight
+ * entries (owner-only) produce no finding, which is what makes the
+ * migration idempotent across runs.
+ */
+export function collectWidePermissions(
+ vault: string,
+ opts: CollectWidePermissionsOptions = {},
+): WidePermissionFinding[] {
+ const platform = opts.platform ?? process.platform;
+ if (platform === "win32") {
+ const log = opts.log ?? ((m: string): void => void process.stderr.write(`${m}\n`));
+ log("harden-permissions: skipped on win32 (POSIX file modes are not meaningful)");
+ return [];
+ }
+ const root = brainDirs(vault).brain;
+ if (!existsSync(root)) return [];
+ const out: WidePermissionFinding[] = [];
+ const visit = (abs: string): void => {
+ let st;
+ try {
+ st = lstatSync(abs);
+ } catch {
+ return;
+ }
+ // Never chmod through a symlink (it would retarget the link's target).
+ if (st.isSymbolicLink()) return;
+ const isDir = st.isDirectory();
+ if (!isDir && !st.isFile()) return;
+ const mode = st.mode & 0o777;
+ if ((mode & NON_OWNER_MODE_MASK) !== 0) {
+ out.push({ path: vaultRelative(abs, vault), isDir, mode });
+ }
+ if (isDir) {
+ let names: string[];
+ try {
+ names = readdirSync(abs);
+ } catch {
+ return;
+ }
+ for (const name of names) visit(join(abs, name));
+ }
+ };
+ visit(root);
+ return out.toSorted((a, b) => a.path.localeCompare(b.path));
+}
+
export function planRemediation(
findings: RemediationFindings,
opts: PlanRemediationOptions,
): RemediationPlan {
const steps: RemediationStep[] = [];
+ for (const perm of findings.widePermissions ?? []) {
+ steps.push({
+ code: "wide-permissions",
+ action: "harden-permissions",
+ target: perm.path,
+ classification: "auto-safe",
+ detail:
+ `chmod ${perm.isDir ? "0700" : "0600"} ${perm.path} ` +
+ `(currently ${perm.mode.toString(8).padStart(3, "0")})`,
+ });
+ }
+
for (const slug of findings.driftedSlugs) {
steps.push({
code: "content-hash-drift",
@@ -208,6 +303,35 @@ function restampContentHash(vault: string, slug: string): boolean {
}
}
+/**
+ * Chmod a Brain/ entry to owner-only (`0o600` file, `0o700` dir). The
+ * path is re-validated through `ensureInsideVault` and re-stat'd so the
+ * canonical mode is derived at apply time, keeping the operation
+ * idempotent (an already-tight entry writes nothing). Returns true when
+ * a chmod happened, false when the entry is gone, a symlink, or already
+ * owner-only.
+ */
+function hardenPermissions(vault: string, relPath: string): boolean {
+ let abs: string;
+ try {
+ abs = ensureInsideVault(join(vault, relPath), vault);
+ } catch {
+ return false; // path escapes the vault - never touch it
+ }
+ let st;
+ try {
+ st = lstatSync(abs);
+ } catch {
+ return false;
+ }
+ if (st.isSymbolicLink()) return false;
+ const isDir = st.isDirectory();
+ if (!isDir && !st.isFile()) return false;
+ if ((st.mode & NON_OWNER_MODE_MASK) === 0) return false; // already hardened
+ chmodSync(abs, isDir ? DIR_TARGET_MODE : FILE_TARGET_MODE);
+ return true;
+}
+
export function applyRemediation(
vault: string,
plan: RemediationPlan,
@@ -227,8 +351,12 @@ export function applyRemediation(
budget--;
continue;
}
- const didWrite =
- step.action === "restamp-content-hash" ? restampContentHash(vault, step.target) : false;
+ let didWrite = false;
+ if (step.action === "restamp-content-hash") {
+ didWrite = restampContentHash(vault, step.target);
+ } else if (step.action === "harden-permissions") {
+ didWrite = hardenPermissions(vault, step.target);
+ }
if (didWrite) {
applied.push(step);
budget--;
diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.ts
index 620d6ee7..0948b063 100644
--- a/src/core/brain/paths.ts
+++ b/src/core/brain/paths.ts
@@ -42,6 +42,8 @@ export const BRAIN_ROOT_REL = "Brain";
/** Vault-relative Brain subdirectory names. */
export const BRAIN_INBOX_REL = posix.join(BRAIN_ROOT_REL, "inbox");
export const BRAIN_PROCESSED_REL = posix.join(BRAIN_INBOX_REL, "processed");
+/** Write-approval staging area: `Brain/pending/sig-*.md` (A3, t_e540b093). */
+export const BRAIN_PENDING_REL = posix.join(BRAIN_ROOT_REL, "pending");
export const BRAIN_PREFERENCES_REL = posix.join(BRAIN_ROOT_REL, "preferences");
export const BRAIN_RETIRED_REL = posix.join(BRAIN_ROOT_REL, "retired");
export const BRAIN_SKILL_PROPOSALS_REL = posix.join(BRAIN_ROOT_REL, "skill-proposals");
@@ -97,6 +99,8 @@ export interface BrainDirs {
readonly inbox: string;
/** Holding area for signals already folded into a preference. */
readonly processed: string;
+ /** Write-approval staging area for extracted signals awaiting review. */
+ readonly pending: string;
readonly preferences: string;
readonly retired: string;
readonly log: string;
@@ -119,6 +123,7 @@ export function brainDirs(vault: string): BrainDirs {
brain,
inbox: ensureInsideVault(join(vault, BRAIN_INBOX_REL), vault),
processed: ensureInsideVault(join(vault, BRAIN_PROCESSED_REL), vault),
+ pending: ensureInsideVault(join(vault, BRAIN_PENDING_REL), vault),
preferences: ensureInsideVault(join(vault, BRAIN_PREFERENCES_REL), vault),
retired: ensureInsideVault(join(vault, BRAIN_RETIRED_REL), vault),
log: ensureInsideVault(join(vault, BRAIN_LOG_REL), vault),
diff --git a/src/core/brain/pending.ts b/src/core/brain/pending.ts
new file mode 100644
index 00000000..98f0f759
--- /dev/null
+++ b/src/core/brain/pending.ts
@@ -0,0 +1,181 @@
+/**
+ * Write-approval pending queue (A3 / t_e540b093).
+ *
+ * When `write_approval.enabled` is on, extracted signals are STAGED into
+ * `Brain/pending/` instead of `Brain/inbox/` (the frontmatter document is
+ * byte-for-byte identical - staging is purely a change of directory). An
+ * operator then reviews the queue:
+ *
+ * - {@link listPending} enumerate staged signals;
+ * - {@link applyPending} move a staged file into `Brain/inbox/` UNCHANGED
+ * (entity anchors and dedup hash preserved verbatim -
+ * they were resolved at extraction time);
+ * - {@link rejectPending} move a staged file into `Brain/retired/` with
+ * retire-shaped frontmatter (`_status`, `retired_at`,
+ * `retired_reason`), following the retire conventions.
+ *
+ * Applying or rejecting a missing / already-processed id raises the typed
+ * {@link PendingSignalNotFoundError}; it is never a silent no-op.
+ *
+ * The document schema is unchanged - staging and applying reuse the exact
+ * signal file that `writeSignal` produces.
+ */
+
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { atomicCreateFileSyncExclusive } from "../fs-atomic.ts";
+import { discoverConfig } from "../config.ts";
+import type { FrontmatterMap } from "../types.ts";
+import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
+import { brainDirs, ensureInsideVault } from "./paths.ts";
+import { parseSignal, writeSignal, type WriteSignalInput } from "./signal.ts";
+import type { BrainSignal } from "./types.ts";
+
+/** Config key / env twin for the opt-in write-approval queue (default off). */
+export const WRITE_APPROVAL_ENABLED_CONFIG_KEY = "write_approval.enabled";
+export const WRITE_APPROVAL_ENABLED_ENV_KEY = "OPEN_SECOND_BRAIN_WRITE_APPROVAL_ENABLED";
+
+/**
+ * Resolve the write-approval toggle (env wins over config file), mirroring
+ * the A1/A2 flat-key resolvers. Default OFF: absent / any non-`true` value
+ * keeps the direct-to-inbox behaviour byte-for-byte.
+ */
+export function resolveWriteApprovalEnabled(configPath?: string): boolean {
+ const env = process.env[WRITE_APPROVAL_ENABLED_ENV_KEY];
+ const raw =
+ env !== undefined && env !== ""
+ ? env
+ : discoverConfig(configPath).data[WRITE_APPROVAL_ENABLED_CONFIG_KEY];
+ return typeof raw === "string" && raw.trim().toLowerCase() === "true";
+}
+
+/** A signal basename shape: `sig-<YYYY-MM-DD>-<slug>` (no path separators). */
+const SIGNAL_ID_RE = /^sig-\d{4}-\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Typed error for a missing / already-processed pending id (never a no-op). */
+export class PendingSignalNotFoundError extends Error {
+ readonly id: string;
+ constructor(id: string) {
+ super(`pending signal not found: ${JSON.stringify(id)}`);
+ this.name = "PendingSignalNotFoundError";
+ this.id = id;
+ }
+}
+
+/** Typed error for an id whose shape could not be a signal basename. */
+export class InvalidPendingIdError extends Error {
+ readonly id: string;
+ constructor(id: string) {
+ super(`invalid pending signal id ${JSON.stringify(id)} - expected sig-<date>-<slug>`);
+ this.name = "InvalidPendingIdError";
+ this.id = id;
+ }
+}
+
+/** One staged signal: its id, absolute path, and parsed frontmatter. */
+export interface PendingEntry {
+ readonly id: string;
+ readonly path: string;
+ readonly signal: BrainSignal;
+}
+
+export interface StageResult {
+ readonly id: string;
+ readonly path: string;
+}
+
+/**
+ * Stage a signal into `Brain/pending/`. Delegates to {@link writeSignal} with
+ * the pending directory as the target so the staged document is byte-for-byte
+ * identical to what the inbox would have received.
+ */
+export function stagePendingSignal(vault: string, input: WriteSignalInput): StageResult {
+ const res = writeSignal(vault, input, { targetDir: brainDirs(vault).pending });
+ return { id: res.id, path: res.path };
+}
+
+/** Validate a pending id and resolve its absolute path inside `Brain/pending/`. */
+function pendingFilePath(vault: string, id: string): string {
+ if (!SIGNAL_ID_RE.test(id)) throw new InvalidPendingIdError(id);
+ return ensureInsideVault(join(brainDirs(vault).pending, `${id}.md`), vault);
+}
+
+/** List the staged signals in `Brain/pending/`, sorted by id. */
+export function listPending(vault: string): PendingEntry[] {
+ const dir = brainDirs(vault).pending;
+ if (!existsSync(dir)) return [];
+ const out: PendingEntry[] = [];
+ for (const file of readdirSync(dir).toSorted()) {
+ if (!file.startsWith("sig-") || !file.endsWith(".md")) continue;
+ const path = join(dir, file);
+ try {
+ out.push({ id: file.slice(0, -".md".length), path, signal: parseSignal(path) });
+ } catch {
+ // A corrupt staged file must not break the whole listing; skip it.
+ }
+ }
+ return out;
+}
+
+/**
+ * Apply a staged signal: move it into `Brain/inbox/` UNCHANGED. The bytes are
+ * copied verbatim (anchors + dedup hash preserved) and the pending copy is
+ * removed only after the inbox copy lands. A missing id is a typed error.
+ */
+export function applyPending(vault: string, id: string): StageResult {
+ const src = pendingFilePath(vault, id);
+ if (!existsSync(src)) throw new PendingSignalNotFoundError(id);
+ const contents = readFileSync(src, "utf8");
+ const dest = ensureInsideVault(join(brainDirs(vault).inbox, `${id}.md`), vault);
+ // Exclusive create: never clobber an existing inbox file with the same id.
+ atomicCreateFileSyncExclusive(dest, contents);
+ unlinkSync(src);
+ return { id, path: dest };
+}
+
+export interface RejectPendingOptions {
+ /** Injected clock for a deterministic `retired_at`. Defaults to now. */
+ readonly now?: Date;
+}
+
+/**
+ * Reject a staged signal: move it into `Brain/retired/` with retire-shaped
+ * frontmatter (`_status: "retired"`, `retired_at`, `retired_reason`), keeping
+ * the original signal fields for the audit trail. A missing id is a typed
+ * error. The `brain/signal` tag is swapped for `brain/retired` so the moved
+ * file reads as a retired artifact.
+ */
+export function rejectPending(
+ vault: string,
+ id: string,
+ reason: string,
+ opts: RejectPendingOptions = {},
+): StageResult {
+ const src = pendingFilePath(vault, id);
+ if (!existsSync(src)) throw new PendingSignalNotFoundError(id);
+ const now = opts.now ?? new Date();
+
+ const [meta, body] = parseFrontmatter(src);
+ const nextMeta: FrontmatterMap = {};
+ for (const [k, v] of Object.entries(meta)) {
+ if (k === "_status" || k === "retired_at" || k === "retired_reason") continue;
+ if (k === "tags") {
+ const arr = Array.isArray(v) ? [...v] : [];
+ nextMeta["tags"] = arr.map((t) => (t === "brain/signal" ? "brain/retired" : t));
+ continue;
+ }
+ nextMeta[k] = v as never;
+ }
+ nextMeta["_status"] = "retired";
+ nextMeta["retired_at"] = now.toISOString();
+ nextMeta["retired_reason"] = reason;
+
+ const dest = ensureInsideVault(join(brainDirs(vault).retired, `${id}.md`), vault);
+ writeFrontmatterAtomic(dest, nextMeta, body, {
+ overwrite: false,
+ vaultForRelativePath: vault,
+ });
+ unlinkSync(src);
+ return { id, path: dest };
+}
diff --git a/src/core/brain/policy.ts b/src/core/brain/policy.ts
index 17e97d36..2fd38af0 100644
--- a/src/core/brain/policy.ts
+++ b/src/core/brain/policy.ts
@@ -434,6 +434,21 @@ export const DEFAULT_BRAIN_CONFIG: BrainConfig = Object.freeze({
}),
}) as BrainConfig;
+/**
+ * Load the configured snapshot `retention_count`, falling back to the
+ * default when the config file is missing, malformed, or otherwise
+ * unreadable. The destructive-snapshot gate uses this so a vault that
+ * has not run `brain init` still prunes to a sane bound rather than
+ * throwing mid-cleanup. This is the SAME `snapshots.retention_count`
+ * the dream pass reads via `loadBrainConfig`; the safe variant just
+ * tolerates an uninitialised vault the way every other read surface
+ * does.
+ */
+export const loadSnapshotRetentionSafe = makeSafeLoader(
+ (config: BrainConfig) => config.snapshots.retention_count,
+ DEFAULT_BRAIN_CONFIG.snapshots.retention_count,
+);
+
/**
* Serialised default `_brain.yaml`. Hand-formatted to match the design
* doc verbatim — `brain init` writes this byte string so the file the
diff --git a/src/core/brain/signal-retire.ts b/src/core/brain/signal-retire.ts
new file mode 100644
index 00000000..7adb97aa
--- /dev/null
+++ b/src/core/brain/signal-retire.ts
@@ -0,0 +1,237 @@
+/**
+ * Fact signal retire lifecycle (A5 / t_66c12a67).
+ *
+ * `retireSignal` moves an extracted fact signal out of `Brain/inbox/` and
+ * into `Brain/retired/`, rewriting its frontmatter with the retire
+ * metadata. It mirrors two existing conventions:
+ *
+ * - `preference.ts` `moveToRetired` - the retire frontmatter shape
+ * (`_status: "retired"`, `retired_at`, `retired_reason`, optional
+ * `superseded_by`, `retired_by`, old-id alias) and the write-then-
+ * unlink move with a dir-containment precondition.
+ * - `pending.ts` `rejectPending` - the signal-specific shape: the file
+ * KEEPS `kind: brain-signal` (a retired signal is still a signal,
+ * readable via `parseSignal`) and the `brain/signal` tag is swapped
+ * for `brain/retired`.
+ *
+ * Because the dream pass consumes `Brain/inbox/` only, the directory move
+ * IS the exclusion mechanism - a retired signal stops being dream intake
+ * yet stays readable in `Brain/retired/`.
+ *
+ * Signals have no per-signal audit file (only preferences do, via
+ * `appendPrefAudit`), so the retire is recorded as a dedicated
+ * `signal-retire` brain log event instead.
+ *
+ * Retiring a missing, already-retired, or non-signal id is a typed error,
+ * never a silent no-op.
+ */
+
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendLogEvent } from "./log.ts";
+import { brainDirs, ensureInsideVault } from "./paths.ts";
+import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
+import { isoSecond } from "./time.ts";
+import { BRAIN_LOG_EVENT_KIND } from "./types.ts";
+import type { FrontmatterMap } from "../types.ts";
+
+/** A signal basename shape: `sig-<YYYY-MM-DD>-<slug>` (no path separators). */
+const SIGNAL_ID_RE = /^sig-\d{4}-\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Retired-preference id prefix; a `ret-*` id is already a retired artifact. */
+const RETIRED_ID_PREFIX = "ret-";
+
+/** Typed error for a signal id that could never be an inbox signal. */
+export class InvalidSignalIdError extends Error {
+ readonly id: string;
+ constructor(id: string) {
+ super(`invalid signal id ${JSON.stringify(id)} - expected sig-<date>-<slug>`);
+ this.name = "InvalidSignalIdError";
+ this.id = id;
+ }
+}
+
+/** Typed error for a signal id absent from `Brain/inbox/` (never a no-op). */
+export class SignalNotFoundError extends Error {
+ readonly id: string;
+ constructor(id: string) {
+ super(`signal not found in inbox: ${JSON.stringify(id)}`);
+ this.name = "SignalNotFoundError";
+ this.id = id;
+ }
+}
+
+/** Typed error for a signal that is already retired (never a no-op). */
+export class SignalAlreadyRetiredError extends Error {
+ readonly id: string;
+ constructor(id: string) {
+ super(`signal already retired: ${JSON.stringify(id)}`);
+ this.name = "SignalAlreadyRetiredError";
+ this.id = id;
+ }
+}
+
+export interface RetireSignalOptions {
+ /** Free-form retirement reason (required). */
+ readonly reason: string;
+ /** Optional pointer to the signal / preference that supersedes this one. */
+ readonly superseded_by?: string;
+ /** Agent identity stamped as `retired_by` and onto the audit event. */
+ readonly agent?: string;
+ /** Injected clock for a deterministic `retired_at`. Defaults to now. */
+ readonly now?: Date;
+}
+
+export interface RetireSignalResult {
+ readonly id: string;
+ readonly path: string;
+}
+
+/**
+ * Retire an extracted fact signal by id. Moves `Brain/inbox/<id>.md` into
+ * `Brain/retired/<id>.md` with retire frontmatter and appends a
+ * `signal-retire` audit event. Throws a typed error when the id is not a
+ * signal shape, is already retired, or is absent from the inbox.
+ */
+export function retireSignal(
+ vault: string,
+ id: string,
+ opts: RetireSignalOptions,
+): RetireSignalResult {
+ const trimmed = id.trim();
+
+ // A `ret-*` id is already a retired artifact - retiring it is a no-op we
+ // refuse loudly.
+ if (trimmed.startsWith(RETIRED_ID_PREFIX)) {
+ throw new SignalAlreadyRetiredError(trimmed);
+ }
+ // Anything that is not a signal basename cannot be an inbox signal. The
+ // regex also closes path traversal (no separators survive it), which is
+ // the containment precondition before any filesystem path is formed.
+ if (!SIGNAL_ID_RE.test(trimmed)) {
+ throw new InvalidSignalIdError(trimmed);
+ }
+
+ const dirs = brainDirs(vault);
+ const srcPath = ensureInsideVault(join(dirs.inbox, `${trimmed}.md`), vault);
+ const destPath = ensureInsideVault(join(dirs.retired, `${trimmed}.md`), vault);
+
+ if (!existsSync(srcPath)) {
+ // Already moved into retired/ -> already retired; otherwise genuinely
+ // missing. Both are typed errors, never a silent no-op.
+ if (existsSync(destPath)) {
+ throw new SignalAlreadyRetiredError(trimmed);
+ }
+ throw new SignalNotFoundError(trimmed);
+ }
+
+ const [meta, body] = parseFrontmatter(srcPath);
+ if (meta["kind"] !== "brain-signal") {
+ throw new InvalidSignalIdError(trimmed);
+ }
+ // Defensive: an inbox file already carrying retire metadata is retired.
+ if (meta["_status"] === "retired") {
+ throw new SignalAlreadyRetiredError(trimmed);
+ }
+
+ const now = opts.now ?? new Date();
+ const nextMeta = rewriteToRetired(meta, trimmed, opts, now);
+
+ // Write-then-unlink: the retired copy must land before the inbox copy is
+ // removed, so a failed write leaves the source untouched. Exclusive
+ // create (overwrite: false) never clobbers an existing retired file.
+ writeFrontmatterAtomic(destPath, nextMeta, body, {
+ overwrite: false,
+ existsErrorKind: "retired",
+ vaultForRelativePath: vault,
+ });
+ if (!existsSync(destPath)) {
+ throw new Error(`retireSignal: write of ${destPath} reported success but file is absent`);
+ }
+ unlinkSync(srcPath);
+
+ // Audit: signals have no per-signal audit file, so the retire lands as a
+ // dedicated brain log event. Fail-soft - a log failure must not undo the
+ // completed move.
+ try {
+ appendLogEvent(vault, {
+ timestamp: isoSecond(now),
+ eventType: BRAIN_LOG_EVENT_KIND.signalRetire,
+ ...(opts.agent ? { agent: opts.agent } : {}),
+ body: {
+ signal: `[[${trimmed}]]`,
+ reason: opts.reason,
+ ...(opts.superseded_by?.trim() ? { superseded_by: opts.superseded_by.trim() } : {}),
+ ...(opts.agent ? { agent: opts.agent } : {}),
+ },
+ });
+ } catch (err) {
+ process.stderr.write(`warning: append signal-retire log failed: ${(err as Error).message}\n`);
+ }
+
+ return { id: trimmed, path: destPath };
+}
+
+/**
+ * Build the retired frontmatter from a signal's original frontmatter,
+ * mirroring `rejectPending` (kind unchanged, `brain/signal` tag swapped)
+ * and `moveToRetired` (retire metadata + old-id alias). Every inherited
+ * signal field is preserved so the retired file stays a readable signal
+ * and a faithful audit snapshot.
+ */
+function rewriteToRetired(
+ meta: FrontmatterMap,
+ id: string,
+ opts: RetireSignalOptions,
+ now: Date,
+): FrontmatterMap {
+ const nextMeta: FrontmatterMap = {};
+ for (const [k, v] of Object.entries(meta)) {
+ // Retire fields are stamped below; drop any pre-existing copies.
+ if (
+ k === "_status" ||
+ k === "retired_at" ||
+ k === "retired_reason" ||
+ k === "retired_by" ||
+ k === "superseded_by"
+ ) {
+ continue;
+ }
+ if (k === "tags") {
+ const arr = Array.isArray(v) ? [...v] : [];
+ nextMeta["tags"] = arr.map((t) => (t === "brain/signal" ? "brain/retired" : t));
+ continue;
+ }
+ if (k === "aliases") {
+ // Preserved and extended below.
+ continue;
+ }
+ nextMeta[k] = v as never;
+ }
+
+ nextMeta["_status"] = "retired";
+ nextMeta["retired_at"] = now.toISOString();
+ nextMeta["retired_reason"] = opts.reason;
+ if (opts.agent?.trim()) {
+ nextMeta["retired_by"] = opts.agent.trim();
+ }
+ if (opts.superseded_by?.trim()) {
+ nextMeta["superseded_by"] = opts.superseded_by.trim();
+ }
+
+ // Old-id alias so any `[[sig-...]]` wikilink keeps resolving after the
+ // move, mirroring moveToRetired. The basename is unchanged (per
+ // rejectPending), so this is belt-and-suspenders but keeps the retire
+ // conventions uniform across preferences and signals.
+ const existingAliases = Array.isArray(meta["aliases"])
+ ? (meta["aliases"] as ReadonlyArray<string>)
+ : [];
+ if (!existingAliases.includes(id)) {
+ nextMeta["aliases"] = [id, ...existingAliases];
+ } else {
+ nextMeta["aliases"] = [...existingAliases];
+ }
+
+ return nextMeta;
+}
diff --git a/src/core/brain/signal.ts b/src/core/brain/signal.ts
index f698d5e2..488d8371 100644
--- a/src/core/brain/signal.ts
+++ b/src/core/brain/signal.ts
@@ -154,6 +154,14 @@ export interface WriteSignalOptions {
* scope-less behaviour is byte-identical.
*/
readonly defaultScope?: string;
+ /**
+ * Absolute target directory for the signal file (A3 / t_e540b093).
+ * Absent: writes to `Brain/inbox/` exactly as before - the default path
+ * stays byte-for-byte identical. Supplied (e.g. `Brain/pending/`) it
+ * stages the IDENTICAL frontmatter document elsewhere; the caller is
+ * responsible for passing a directory that resolves inside the vault.
+ */
+ readonly targetDir?: string;
}
/**
@@ -280,7 +288,7 @@ export function writeSignal(
const dirs = brainDirs(vault);
const allocated = allocateSlug({
vault,
- targetDir: dirs.inbox,
+ targetDir: options.targetDir ?? dirs.inbox,
prefix: signalPrefix(sanitised.date),
slug: sanitised.slug,
maxAttempts: options.maxSlugAttempts,
diff --git a/src/core/brain/snapshot-gate.ts b/src/core/brain/snapshot-gate.ts
new file mode 100644
index 00000000..f51e46eb
--- /dev/null
+++ b/src/core/brain/snapshot-gate.ts
@@ -0,0 +1,123 @@
+/**
+ * Snapshot-before-destructive-write gate (D1 / t_7965b04b).
+ *
+ * A thin wrapper over the existing `snapshot.ts` engine that makes one
+ * guarantee: no destructive brain mutation runs without a recovery
+ * point on disk first. The wrapper mints a validated, unique run id,
+ * calls {@link createSnapshot} BEFORE the operation, runs the
+ * operation, then prunes to the configured retention.
+ *
+ * Failure semantics (the reason this is a gate and not a helper):
+ *
+ * - If the snapshot cannot be written, the typed snapshot error
+ * propagates and `op` NEVER runs - a destructive operation that
+ * cannot be protected must abort, never proceed unprotected.
+ * - If `op` throws, the error propagates but the snapshot STAYS on
+ * disk - it is precisely the recovery point the caller needs. We
+ * therefore skip the post-run prune on the throwing path.
+ *
+ * The engine module (656 lines) stays untouched; this sibling only
+ * composes its public functions.
+ */
+
+import { existsSync } from "node:fs";
+
+import { loadSnapshotRetentionSafe } from "./policy.ts";
+import { snapshotPath, validateRunId } from "./paths.ts";
+import { createSnapshot, pruneSnapshots } from "./snapshot.ts";
+import { compactRunStamp } from "./time.ts";
+
+/** The recovery point minted for a destructive operation. */
+export interface DestructiveSnapshot {
+ /** Validated run id of the archive (`<label>-<stamp>`). */
+ readonly runId: string;
+ /** Absolute path of the snapshot archive. */
+ readonly path: string;
+}
+
+export interface WithDestructiveSnapshotResult<T> {
+ readonly snapshot: DestructiveSnapshot;
+ readonly result: T;
+}
+
+export interface WithDestructiveSnapshotOptions {
+ /** Injected clock so callers can mint deterministic run ids in tests. */
+ readonly now?: Date;
+}
+
+/** Upper bound on run-id collision retries before giving up. */
+const MAX_SNAPSHOT_ID_ATTEMPTS = 64;
+
+/**
+ * Create the recovery snapshot behind a unique run id. Selection and
+ * creation are fused so a concurrent process cannot win the id between an
+ * availability probe and the write: we start from `<label>-<compactStamp>`,
+ * append `-2`, `-3`, ... on collision, and RETRY `createSnapshot` when the
+ * write fails because the archive now exists (a racing process claimed it).
+ * Any other create failure (missing tooling, unwritable archive) propagates
+ * on the first attempt. Mirrors the collision strategy `nextAvailableDreamRunId`
+ * uses in `dream.ts`, but closes the check-then-write race window.
+ */
+function createUniqueSnapshot(
+ vault: string,
+ baseRunId: string,
+): { runId: string; snapshot: ReturnType<typeof createSnapshot> } {
+ for (let n = 1; n <= MAX_SNAPSHOT_ID_ATTEMPTS; n++) {
+ const candidate = n === 1 ? baseRunId : `${baseRunId}-${n}`;
+ if (existsSync(snapshotPath(vault, candidate))) continue;
+ try {
+ return { runId: candidate, snapshot: createSnapshot(vault, candidate) };
+ } catch (err) {
+ // A concurrent op may have created this archive between our probe and
+ // the write; createSnapshot refuses to overwrite. Retry the next id
+ // only for that collision - any other failure is a real error.
+ if (!existsSync(snapshotPath(vault, candidate))) throw err;
+ }
+ }
+ throw new Error(
+ `could not reserve a unique snapshot run id from "${baseRunId}" after ${MAX_SNAPSHOT_ID_ATTEMPTS} attempts`,
+ );
+}
+
+/**
+ * Run `op` behind a pre-operation snapshot. Returns the recovery point
+ * alongside the operation's result. See the module header for the
+ * abort / retain failure semantics.
+ */
+export function withDestructiveSnapshot<T>(
+ vault: string,
+ label: string,
+ op: () => T,
+ opts: WithDestructiveSnapshotOptions = {},
+): WithDestructiveSnapshotResult<T> {
+ // validateRunId rejects a label that would form a filesystem-unsafe
+ // id (separators, traversal, Windows-reserved) - a typed error before
+ // any snapshot or mutation is attempted.
+ const baseRunId = validateRunId(`${label}-${compactRunStamp(opts.now ?? new Date())}`);
+
+ // Snapshot FIRST, behind a collision-safe unique id. A throw here (missing
+ // tooling, unwritable archive) aborts before `op` runs - the destructive
+ // work never happens.
+ const { runId, snapshot: snap } = createUniqueSnapshot(vault, baseRunId);
+
+ // Run the destructive operation. If it throws, we deliberately do NOT
+ // prune: the archive we just wrote is the recovery point, and letting
+ // the error propagate keeps it in place.
+ const result = op();
+
+ // Prune is best-effort: the destructive op has already committed, so a
+ // prune failure must NOT surface as an operation failure (that could
+ // trigger an unsafe retry of committed work). Retention is a cleanup
+ // concern, not a correctness one - warn and keep the successful result.
+ try {
+ pruneSnapshots(vault, loadSnapshotRetentionSafe(vault));
+ } catch (err) {
+ process.stderr.write(
+ `warning: snapshot prune after ${runId} failed (operation already committed): ${
+ (err as Error).message ?? String(err)
+ }\n`,
+ );
+ }
+
+ return { snapshot: { runId, path: snap.path }, result };
+}
diff --git a/src/core/brain/source-cleanup.ts b/src/core/brain/source-cleanup.ts
index 19642141..9b513dd4 100644
--- a/src/core/brain/source-cleanup.ts
+++ b/src/core/brain/source-cleanup.ts
@@ -58,6 +58,10 @@ import { BRAIN_SOURCE_KIND } from "./ingest/ingest.ts";
import { manifestPath, readManifest, writeManifestAtomic } from "./ingest/content-manifest.ts";
import { appendContinuitySourceInvalidation } from "./continuity/store.ts";
import { isoSecond } from "./time.ts";
+import { withDestructiveSnapshot } from "./snapshot-gate.ts";
+
+/** Run-id label for the snapshot taken before a confirmed source cleanup. */
+const DELETE_BY_SOURCE_SNAPSHOT_LABEL = "delete-by-source";
/** How a page was found to trace back to the source. */
export type SourceCleanupMatch = "source_path" | "session_ref" | "wikilink" | "evidenced_by";
@@ -109,6 +113,14 @@ export interface SourceCleanupPlan {
readonly manifestEntryRemoved: boolean;
/** Id of the audit continuity record, when one was written. */
readonly auditRecordId: string | null;
+ /**
+ * Run id of the pre-deletion snapshot taken behind the D1 gate, or
+ * null when none was taken (a dry run, or a confirmed run with nothing
+ * to delete). This is the recovery point the operator can roll back to.
+ */
+ readonly snapshotRunId: string | null;
+ /** Absolute path of the snapshot archive, paired with {@link snapshotRunId}. */
+ readonly snapshotPath: string | null;
/** Total referencing pages + originals (the reported blast radius). */
readonly blastRadius: number;
}
@@ -498,6 +510,8 @@ export function deleteBySource(
deleted: Object.freeze([]),
manifestEntryRemoved: false,
auditRecordId: null,
+ snapshotRunId: null,
+ snapshotPath: null,
blastRadius,
});
}
@@ -525,37 +539,61 @@ export function deleteBySource(
};
let auditRecordId: string | null = null;
- try {
- for (const entry of derived) {
- if (removeFile(vault, entry.path)) deleted.push(entry.path);
- }
- if (includeOriginals) {
- for (const original of originals) {
- if (removeFile(vault, original)) deleted.push(original);
+
+ // The destructive core: remove derived entries, opt-in originals, and
+ // the manifest index entry, then audit. Runs behind the D1 snapshot
+ // gate so every confirmed cleanup has a pre-deletion recovery point.
+ const runDeletion = (): void => {
+ try {
+ for (const entry of derived) {
+ if (removeFile(vault, entry.path)) deleted.push(entry.path);
+ }
+ if (includeOriginals) {
+ for (const original of originals) {
+ if (removeFile(vault, original)) deleted.push(original);
+ }
}
- }
- if (manifestKey !== null && existsSync(manifestPath(vault))) {
- const entries = { ...readManifest(vault).entries };
- if (entries[manifestKey] !== undefined) {
- delete entries[manifestKey];
- manifestEntryRemoved = writeManifestAtomic(vault, entries);
+ if (manifestKey !== null && existsSync(manifestPath(vault))) {
+ const entries = { ...readManifest(vault).entries };
+ if (entries[manifestKey] !== undefined) {
+ delete entries[manifestKey];
+ manifestEntryRemoved = writeManifestAtomic(vault, entries);
+ }
}
+ } catch (err) {
+ // A removeFile (or manifest write) that throws mid-cleanup would otherwise
+ // exit before the audit append, leaving already-deleted paths with no
+ // record for a retry to reconstruct. Persist what was removed so far, then
+ // rethrow; never let an audit-write error mask the original failure.
+ try {
+ writeInvalidationAudit();
+ } catch {
+ /* swallow: the original error below is the one that matters */
+ }
+ throw err;
}
- } catch (err) {
- // A removeFile (or manifest write) that throws mid-cleanup would otherwise
- // exit before the audit append, leaving already-deleted paths with no
- // record for a retry to reconstruct. Persist what was removed so far, then
- // rethrow; never let an audit-write error mask the original failure.
- try {
- writeInvalidationAudit();
- } catch {
- /* swallow: the original error below is the one that matters */
- }
- throw err;
- }
+ auditRecordId = writeInvalidationAudit();
+ };
- auditRecordId = writeInvalidationAudit();
+ // Only snapshot when there is something to remove. A confirmed run over
+ // a source with no derived material, no included originals, and no
+ // manifest entry is a no-op and must stay one - snapshotting an empty
+ // deletion would churn `.snapshots/` for nothing.
+ const hasWork =
+ derived.length > 0 || (includeOriginals && originals.length > 0) || manifestKey !== null;
+
+ let snapshotRunId: string | null = null;
+ let snapshotArchivePath: string | null = null;
+ if (hasWork) {
+ const gated = withDestructiveSnapshot(vault, DELETE_BY_SOURCE_SNAPSHOT_LABEL, runDeletion, {
+ now: opts.now,
+ });
+ snapshotRunId = gated.snapshot.runId;
+ snapshotArchivePath = gated.snapshot.path;
+ } else {
+ runDeletion();
+ }
return Object.freeze({
source: canonical,
@@ -568,6 +606,8 @@ export function deleteBySource(
deleted: Object.freeze(deleted),
manifestEntryRemoved,
auditRecordId,
+ snapshotRunId,
+ snapshotPath: snapshotArchivePath,
blastRadius,
});
}
diff --git a/src/core/brain/time.ts b/src/core/brain/time.ts
index eb9c7c89..6f48ba3f 100644
--- a/src/core/brain/time.ts
+++ b/src/core/brain/time.ts
@@ -26,6 +26,24 @@ export function isoDate(d: Date = new Date()): string {
return d.toISOString().slice(0, 10);
}
+/**
+ * Compact UTC run-id stamp (`YYYY-MM-DD-HHMMSS`). Whole-second
+ * precision, no separators inside the time-of-day segment, so the
+ * result is a filesystem-safe run-id stem under
+ * {@link validateRunId} (`[A-Za-z0-9][A-Za-z0-9._-]*`). Shared by the
+ * `dream` run-id formatter and the destructive-snapshot gate so both
+ * mint ids the same way.
+ */
+export function compactRunStamp(d: Date = new Date()): string {
+ const yyyy = d.getUTCFullYear().toString().padStart(4, "0");
+ const mm = (d.getUTCMonth() + 1).toString().padStart(2, "0");
+ const dd = d.getUTCDate().toString().padStart(2, "0");
+ const hh = d.getUTCHours().toString().padStart(2, "0");
+ const mi = d.getUTCMinutes().toString().padStart(2, "0");
+ const ss = d.getUTCSeconds().toString().padStart(2, "0");
+ return `${yyyy}-${mm}-${dd}-${hh}${mi}${ss}`;
+}
+
/**
* Render the gap between an ISO-8601 timestamp and `now` as a short,
* human-readable relative-age label — "just now", "3m ago", "2h ago",
diff --git a/src/core/brain/types.ts b/src/core/brain/types.ts
index 06cea362..e4cb513d 100644
--- a/src/core/brain/types.ts
+++ b/src/core/brain/types.ts
@@ -240,6 +240,15 @@ export const BRAIN_LOG_EVENT_KIND = {
* file - the log records outcomes, not chatter.
*/
writeSession: "write-session",
+ /**
+ * `entity-anchor-skip` (A1, t_657b365e) - fact-extract anchoring skipped a
+ * registered entity whose stored label fails the label quality gate
+ * (structurally junk after decoration stripping). Payload carries the
+ * entity `id`, the raw `name`, and the rejection `reason`. The skip is
+ * contained: it never breaks the enclosing capture, and `doctor` surfaces
+ * the same node as a `entity-label-malformed` prune candidate.
+ */
+ entityAnchorSkip: "entity-anchor-skip",
/**
* `attribute-write` (today-operator-surface, t_d7be2a0c) - one audit
* row per applied `@osb set` marker write-back. Payload carries the
@@ -250,6 +259,38 @@ export const BRAIN_LOG_EVENT_KIND = {
* no extra wiring.
*/
attributeWrite: "attribute-write",
+ /**
+ * `durability-skip` (A2, t_375e98fd) - the deterministic durability gate
+ * rejected an extracted fact as transient operational content before it
+ * reached the inbox. Payload carries the `family`, the structural
+ * `reason` that fired (e.g. `temp-path`, `progress-counter`), a
+ * secret-redacted `text` excerpt, the `hash` (dedup hash of the rejected
+ * fact for correlation), and the `agent`. The skip is never silent: this
+ * dedicated, queryable event kind IS the visibility surface, so rejection
+ * counts are discoverable through the log without a separate aggregator.
+ */
+ durabilitySkip: "durability-skip",
+ /**
+ * `write-conflict-advisory` (A4, t_f79b4fe0) - a feedback signal was
+ * written whose principle closely resembles one or more confirmed
+ * same-scope preferences. The advisory NEVER blocks the write; this
+ * event is its durable, queryable record. Payload carries the `scope`
+ * bucket, the resembling preferences (`conflicts`, one wikilink +
+ * jaccard per line), and the `agent`. Fires only on the operator-facing
+ * feedback path, never on the extracted-fact path, so the two never
+ * double-fire on a single write.
+ */
+ writeConflictAdvisory: "write-conflict-advisory",
+ /**
+ * `signal-retire` (A5, t_66c12a67) - an extracted fact signal was
+ * retired: moved from `Brain/inbox/` into `Brain/retired/` with retire
+ * metadata. Signals have no per-signal audit file (only preferences do),
+ * so this dedicated log event IS the audit trail. Payload carries the
+ * retired `signal` wikilink, the `reason`, an optional `superseded_by`
+ * pointer, and the `agent`. The directory move is what excludes the
+ * signal from the dream pass; this event records that it happened.
+ */
+ signalRetire: "signal-retire",
} as const;
export type BrainLogEventKind = (typeof BRAIN_LOG_EVENT_KIND)[keyof typeof BRAIN_LOG_EVENT_KIND];
diff --git a/src/core/brain/write-advisory.ts b/src/core/brain/write-advisory.ts
new file mode 100644
index 00000000..818ea4b1
--- /dev/null
+++ b/src/core/brain/write-advisory.ts
@@ -0,0 +1,146 @@
+/**
+ * A4 (t_f79b4fe0): write-time conflict advisory seam.
+ *
+ * When an operator records a feedback signal, this seam compares the
+ * incoming principle against confirmed same-scope preferences and, when a
+ * near-duplicate is found, returns a non-blocking advisory naming the
+ * resembling preference ids. The advisory is surfaced in the feedback
+ * response / CLI output and logged under a dedicated event kind.
+ *
+ * Two invariants, straight from the design doc:
+ *
+ * - The write ALWAYS proceeds. This helper runs AROUND the write and
+ * never gates it. Advisory computation is best-effort: a failure
+ * (e.g. an unreadable preferences dir) degrades to a visible stderr
+ * warning and a `null` result, never a swallowed exception and never a
+ * failed feedback call.
+ * - The advisory fires only on the operator-facing feedback path, NOT
+ * inside `routeExtractedFacts`, so the extracted-fact path and the
+ * feedback path never double-fire on a single write.
+ *
+ * Only the incoming signal's scope bucket is read (confirmed preferences
+ * whose scope matches the incoming scope; an unscoped signal compares
+ * against the unscoped bucket), mirroring `detectContradictions`.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { adviseOnIncoming, type PreferenceForContradiction } from "./health/contradiction.ts";
+import { appendLogEvent } from "./log.ts";
+import { brainDirs } from "./paths.ts";
+import { parsePreference } from "./preference.ts";
+import { isoSecond } from "./time.ts";
+import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "./types.ts";
+
+/** One resembling preference: its id and the incoming-vs-confirmed jaccard. */
+export interface WriteConflictEvidence {
+ readonly pref_id: string;
+ readonly jaccard: number;
+}
+
+/**
+ * The advisory surfaced to the feedback response / CLI output. Present
+ * only when at least one confirmed same-scope preference clears the
+ * similarity threshold.
+ */
+export interface WriteConflictAdvisory {
+ /** The scope bucket compared against; `null` for the unscoped bucket. */
+ readonly scope: string | null;
+ /** Non-empty, sorted by descending similarity then id. */
+ readonly conflicts: ReadonlyArray<WriteConflictEvidence>;
+}
+
+export interface AdviseIncomingFeedbackParams {
+ /** The incoming feedback principle to compare. */
+ readonly principle: string;
+ /** The signal's effective scope (already resolved against the default). */
+ readonly scope?: string;
+ /** Agent identity stamped on the advisory log event. */
+ readonly agent: string;
+ /** Injected clock for a deterministic log timestamp. Defaults to now. */
+ readonly now?: Date;
+}
+
+/**
+ * Load the confirmed preferences in the incoming signal's scope bucket.
+ * Scope-bucket loading only: preferences in a different scope (and every
+ * non-confirmed preference) are dropped here rather than compared. A
+ * corrupt / mis-foldered preference file is skipped (that is the doctor's
+ * concern, not the write path's).
+ */
+function loadConfirmedScopePrefs(
+ vault: string,
+ scope: string | undefined,
+): PreferenceForContradiction[] {
+ const dir = brainDirs(vault).preferences;
+ if (!existsSync(dir)) return [];
+ const bucketKey = scope ?? "";
+ const out: PreferenceForContradiction[] = [];
+ for (const name of readdirSync(dir)) {
+ if (!name.endsWith(".md")) continue;
+ let pref;
+ try {
+ pref = parsePreference(join(dir, name));
+ } catch {
+ continue;
+ }
+ if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;
+ if ((pref.scope ?? "") !== bucketKey) continue;
+ out.push(pref);
+ }
+ return out;
+}
+
+/**
+ * Compute (and log) the write-time conflict advisory for an incoming
+ * feedback signal. Returns the advisory when a confirmed same-scope
+ * preference resembles the incoming principle, otherwise `null`.
+ *
+ * Never throws: any failure is reported as a stderr warning and returns
+ * `null`, so the surrounding feedback write is never affected.
+ */
+export function adviseIncomingFeedback(
+ vault: string,
+ params: AdviseIncomingFeedbackParams,
+): WriteConflictAdvisory | null {
+ try {
+ const prefs = loadConfirmedScopePrefs(vault, params.scope);
+ const advisory = adviseOnIncoming(params.principle, params.scope, prefs);
+ if (advisory === null) return null;
+
+ const result: WriteConflictAdvisory = {
+ scope: advisory.scope,
+ conflicts: advisory.conflicts.map((c) => ({ pref_id: c.prefId, jaccard: c.jaccard })),
+ };
+
+ try {
+ appendLogEvent(vault, {
+ timestamp: isoSecond(params.now ?? new Date()),
+ eventType: BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
+ agent: params.agent,
+ body: {
+ scope: advisory.scope ?? "(unscoped)",
+ // One bullet per resembling preference: wikilink + similarity, so
+ // the audit row is both human-readable and grep-friendly.
+ conflicts: result.conflicts.map(
+ (c) => `[[${c.pref_id}]] jaccard=${c.jaccard.toFixed(3)}`,
+ ),
+ agent: params.agent,
+ },
+ });
+ } catch (err) {
+ process.stderr.write(
+ `warning: append write-conflict-advisory log failed: ${(err as Error).message}\n`,
+ );
+ }
+
+ return result;
+ } catch (err) {
+ // Advisory computation is best-effort and NEVER blocks the write.
+ process.stderr.write(
+ `warning: write-conflict advisory computation failed: ${(err as Error).message}\n`,
+ );
+ return null;
+ }
+}
diff --git a/src/core/config.ts b/src/core/config.ts
index 101c7290..8f2103b2 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -8,7 +8,7 @@
*/
import { mkdirSync, readFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
import { homedir } from "node:os";
import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -261,6 +261,39 @@ export function resolveDeviceId(configPath?: string): string {
}
}
+/**
+ * Store-hardening escape hatch (D2). Default OFF: MCP responses redact
+ * the absolute vault host path to an opaque store reference (see
+ * {@link vaultStoreReference}) because those responses land in model
+ * context - the exact leak surface this guards. Set
+ * `expose_host_paths: true` (or the env twin) to restore the raw path
+ * for operators whose tooling depends on it.
+ */
+export function resolveExposeHostPaths(configPath?: string): boolean {
+ return resolveConfigFlag("OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS", "expose_host_paths", configPath);
+}
+
+/** Prefix of the opaque store reference emitted in place of a host path. */
+export const VAULT_STORE_REF_PREFIX = "vault://";
+/** Hex length of the store-reference digest. */
+const VAULT_STORE_REF_HEX_LEN = 8;
+
+/**
+ * Stable opaque reference for a vault, of the form `vault://<8-hex>`.
+ * Derived from the device-id primitive plus a hash of the vault path, so
+ * it is stable across calls on the same install (agents correlate by it)
+ * and does not leak the absolute host path. Returned by MCP tools in
+ * place of the raw path unless {@link resolveExposeHostPaths} is on.
+ */
+export function vaultStoreReference(vaultPath: string, configPath?: string): string {
+ const deviceId = resolveDeviceId(configPath);
+ const digest = createHash("sha256")
+ .update(`${deviceId}\0${vaultPath}`)
+ .digest("hex")
+ .slice(0, VAULT_STORE_REF_HEX_LEN);
+ return `${VAULT_STORE_REF_PREFIX}${digest}`;
+}
+
export function resolveLinkOutputFormat(configPath?: string): LinkOutputFormat {
const env = process.env["OBSIDIAN_LINK_FORMAT"]?.trim();
const data = env ? {} : discoverConfig(configPath).data;
diff --git a/src/core/path-safety.ts b/src/core/path-safety.ts
index 7efb70cd..70026c4a 100644
--- a/src/core/path-safety.ts
+++ b/src/core/path-safety.ts
@@ -43,17 +43,28 @@ export function ensureInsideVault(target: string, vault: string): string {
// Realpath protection only matters when the vault actually exists on
// disk — otherwise there is no symlink to follow. Pure-lexical inputs
// (used by unit tests) skip this branch and rely on step 1 above.
- if (existsSync(resolvedVault)) {
- const realVault = safeRealpath(resolvedVault);
- const realAncestor = safeRealpath(deepestExistingAncestor(resolvedTarget));
- if (!isLexicallyInside(realAncestor, realVault)) {
- throw new Error(`path escapes vault via symlink: ${target}`);
- }
+ if (existsSync(resolvedVault) && !realpathInsideVault(resolvedTarget, resolvedVault)) {
+ throw new Error(`path escapes vault via symlink: ${target}`);
}
return resolvedTarget;
}
+/**
+ * Step 2 of {@link ensureInsideVault} as a non-throwing predicate: does
+ * `target`'s realpath (following symlinks for its deepest existing
+ * ancestor) resolve inside `vault`? Returns true when the vault does not
+ * exist on disk (no symlink to follow). Shared with the doctor's
+ * `symlink-escape` lint so the two-step check lives in exactly one place.
+ */
+export function realpathInsideVault(target: string, vault: string): boolean {
+ const resolvedVault = resolve(vault);
+ if (!existsSync(resolvedVault)) return true;
+ const realVault = safeRealpath(resolvedVault);
+ const realAncestor = safeRealpath(deepestExistingAncestor(resolve(target)));
+ return isLexicallyInside(realAncestor, realVault);
+}
+
function isLexicallyInside(target: string, root: string): boolean {
// Windows file paths are case-insensitive at the filesystem level —
// `C:\Vault\x.md` and `c:\vault\x.md` resolve to the same inode. Doing
diff --git a/src/core/search/embeddings/contract.ts b/src/core/search/embeddings/contract.ts
index e91030e3..af1d8668 100644
--- a/src/core/search/embeddings/contract.ts
+++ b/src/core/search/embeddings/contract.ts
@@ -6,11 +6,20 @@
* Anchored in docs/plans/2026-05-16-brain-search-design.md §11.
*/
+/**
+ * Instruction-prefix kind for an embed call (memory-write-path-integrity B2).
+ * Asymmetric-instruction embedding families (e5) expect a different lead-in
+ * for a search query versus an indexed passage. The kind is optional and
+ * additive: a provider that ignores it, or a call that omits it, embeds the
+ * raw text unchanged.
+ */
+export type EmbedKind = "query" | "passage";
+
export interface EmbeddingProvider {
readonly name: string;
readonly model: string;
readonly dimension: number | null;
- embed(texts: ReadonlyArray<string>): Promise<number[][]>;
+ embed(texts: ReadonlyArray<string>, kind?: EmbedKind): Promise<number[][]>;
ping(): Promise<{ ok: true; dimension: number } | { ok: false; reason: string }>;
/**
* Optional read-and-reset of provider-internal retry tally. The
diff --git a/src/core/search/embeddings/http-util.ts b/src/core/search/embeddings/http-util.ts
index 7f8d64f9..d74d5365 100644
--- a/src/core/search/embeddings/http-util.ts
+++ b/src/core/search/embeddings/http-util.ts
@@ -6,14 +6,67 @@
* unit-normalisation semantics.
*/
+import { assertValidVector } from "../vector-guard.ts";
+
/** Statuses that warrant a transient retry with backoff. */
export const RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
/** Auth statuses that trigger failover to the next probe key. */
export const AUTH_STATUSES: ReadonlySet<number> = new Set([401, 403]);
-export function sleep(ms: number): Promise<void> {
- return new Promise((res) => setTimeout(res, ms));
+/** HTTP 402 Payment Required: an unconditional billing/quota exhaustion signal. */
+export const PAYMENT_REQUIRED_STATUS = 402;
+
+/** HTTP 429 Too Many Requests: a rate-limit unless the body proves quota exhaustion. */
+export const RATE_LIMIT_STATUS = 429;
+
+/** Milliseconds per second, used to convert `Retry-After` delta-seconds. */
+const MS_PER_SECOND = 1000;
+
+/**
+ * Parse an HTTP `Retry-After` header value into milliseconds. The header is
+ * either a non-negative integer count of seconds (RFC 7231 delta-seconds) or
+ * an HTTP-date. Returns null when absent or unparseable. `nowMs` is
+ * injectable so date-form parsing stays deterministic in tests.
+ */
+export function parseRetryAfterMs(
+ headerValue: string | null,
+ nowMs: number = Date.now(),
+): number | null {
+ if (headerValue === null) return null;
+ const trimmed = headerValue.trim();
+ if (trimmed === "") return null;
+ // delta-seconds form: a bare non-negative integer.
+ if (/^\d+$/.test(trimmed)) {
+ return Number(trimmed) * MS_PER_SECOND;
+ }
+ // HTTP-date form: convert to a delay relative to now, floored at zero.
+ const dateMs = Date.parse(trimmed);
+ if (Number.isNaN(dateMs)) return null;
+ const delta = dateMs - nowMs;
+ return delta > 0 ? delta : 0;
+}
+
+/**
+ * Delay for `ms`, resolving early (never rejecting) if `signal` aborts. An
+ * abort-aware sleep lets a retry backoff react to cancellation immediately
+ * instead of blocking a sibling batch for up to the retry-after cap after
+ * the shared abort signal fires. The caller re-checks the signal on the next
+ * loop iteration to surface the cancellation.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+ if (signal?.aborted) return Promise.resolve();
+ return new Promise((res) => {
+ const onAbort = (): void => {
+ clearTimeout(timer);
+ res();
+ };
+ const timer = setTimeout(() => {
+ signal?.removeEventListener("abort", onAbort);
+ res();
+ }, ms);
+ signal?.addEventListener("abort", onAbort, { once: true });
+ });
}
/** Apply ±25% jitter to a backoff base (never negative). */
@@ -44,12 +97,18 @@ export class Semaphore {
}
}
-/** Unit-normalise a vector in place so cosine similarity equals 1 - L2²/2. */
+/**
+ * Unit-normalise a vector in place so cosine similarity equals 1 - L2²/2.
+ * A zero-norm or non-finite input has no meaningful unit direction, so it
+ * surfaces a typed {@link SearchError} (`EMBEDDING_INVALID_VECTOR`) rather
+ * than the former silent no-op that returned unnormalised zeros
+ * (memory-write-path-integrity B1).
+ */
export function unitNormaliseInPlace(v: number[]): number[] {
+ assertValidVector(v, "unitNormalise");
let s = 0;
for (const x of v) s += x * x;
const norm = Math.sqrt(s);
- if (norm === 0) return v;
for (let i = 0; i < v.length; i++) v[i] = (v[i] ?? 0) / norm;
return v;
}
diff --git a/src/core/search/embeddings/openai-compat.ts b/src/core/search/embeddings/openai-compat.ts
index ef6cbef1..c4bc2a07 100644
--- a/src/core/search/embeddings/openai-compat.ts
+++ b/src/core/search/embeddings/openai-compat.ts
@@ -17,19 +17,164 @@
* whether to surface (`--semantic`) or warn (implicit).
*/
-import { SearchError } from "../types.ts";
-import type { ResolvedEmbeddingConfig } from "../types.ts";
-import type { EmbeddingProvider } from "./contract.ts";
+import { EMBEDDING_QUOTA_MESSAGE, SearchError } from "../types.ts";
+import type { EmbeddingErrorCategory, ResolvedEmbeddingConfig } from "../types.ts";
+import type { EmbeddingProvider, EmbedKind } from "./contract.ts";
import {
AUTH_STATUSES,
+ PAYMENT_REQUIRED_STATUS,
+ RATE_LIMIT_STATUS,
RETRYABLE_STATUSES,
Semaphore,
chunkArray,
jittered,
+ parseRetryAfterMs,
sleep,
unitNormaliseInPlace,
} from "./http-util.ts";
+/**
+ * Sentinel embedded in a synthetic error message when a batch is cancelled
+ * by the parent abort controller. A cancelled batch must never be retried:
+ * the outer `Promise.all` already gave up on it.
+ */
+const CANCELLED_SENTINEL = "embed cancelled";
+
+/** Max characters of an error response body echoed into the thrown message. */
+const ERROR_BODY_HEAD_LEN = 300;
+
+/** Fallback backoff base (ms) when the configured schedule runs out. */
+const DEFAULT_BACKOFF_MS = 4000;
+
+/**
+ * Upper bound (ms) on how long a provider `Retry-After` is honored before a
+ * retry (Task C2). A cooperative reindex should pause for a short provider
+ * hint, but a multi-minute Retry-After would stall the run; past this cap we
+ * still wait the cap rather than the raw hint. 30s balances respecting the
+ * provider against keeping an interactive reindex responsive.
+ */
+export const RETRY_AFTER_CAP_MS = 30_000;
+
+/**
+ * Delay (ms) before the next retry of a just-failed attempt (1-based
+ * `attempt`). When the provider supplied a `Retry-After`, honor it capped at
+ * `capMs`; otherwise use the configured exponential backoff with jitter.
+ */
+export function computeRetryDelayMs(
+ retryAfterMs: number | null,
+ attempt: number,
+ backoffMs: ReadonlyArray<number>,
+ capMs: number,
+): number {
+ if (retryAfterMs !== null) return Math.min(retryAfterMs, capMs);
+ const base = backoffMs[attempt - 1] ?? backoffMs[backoffMs.length - 1] ?? DEFAULT_BACKOFF_MS;
+ return jittered(base);
+}
+
+/**
+ * OpenAI-compatible provider error `code`/`type` values that denote quota /
+ * billing exhaustion. These are wire-protocol identifiers, not natural
+ * language, so matching them is deterministic and provider-portable.
+ */
+const QUOTA_ERROR_TOKENS: ReadonlySet<string> = new Set(["insufficient_quota"]);
+
+/** Prefix forms of quota tokens (e.g. `billing_hard_limit_reached`). */
+const QUOTA_ERROR_TOKEN_PREFIXES: ReadonlyArray<string> = ["billing"];
+
+function safeParseJson(text: string): unknown {
+ if (text === "") return null;
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function isQuotaToken(value: unknown): boolean {
+ if (typeof value !== "string") return false;
+ const v = value.toLowerCase();
+ if (QUOTA_ERROR_TOKENS.has(v)) return true;
+ return QUOTA_ERROR_TOKEN_PREFIXES.some((prefix) => v.startsWith(prefix));
+}
+
+/**
+ * True when a parsed provider error body carries protocol-token evidence of
+ * quota exhaustion in its `error.code`/`error.type` (or top-level `code`/
+ * `type`) fields. Inspects structured fields only, never prose.
+ */
+function bodyHasQuotaEvidence(parsed: unknown): boolean {
+ if (parsed === null || typeof parsed !== "object") return false;
+ const obj = parsed as Record<string, unknown>;
+ const err = obj["error"];
+ if (err !== null && typeof err === "object") {
+ const e = err as Record<string, unknown>;
+ if (isQuotaToken(e["code"]) || isQuotaToken(e["type"])) return true;
+ }
+ return isQuotaToken(obj["code"]) || isQuotaToken(obj["type"]);
+}
+
+/** Classification of an embedding-provider error (Task C1). */
+export interface EmbeddingErrorClassification {
+ readonly category: EmbeddingErrorCategory;
+ readonly retriable: boolean;
+ readonly retryAfterMs: number | null;
+ readonly error: SearchError;
+}
+
+/**
+ * Classify an embedding-provider error into a coarse category plus retry
+ * policy, reading the structured `status`/`retryAfterMs` fields carried on
+ * the {@link SearchError} - never re-parsing the message string. Non-quota
+ * behaviour matches the pre-C1 retry semantics: 5xx / timeout / network
+ * retry, 4xx (except quota) fail fast, 401/403 stay non-retriable so the
+ * caller's key failover engages.
+ */
+export function classifyEmbeddingError(e: unknown): EmbeddingErrorClassification {
+ if (e instanceof SearchError) {
+ if (e.message.includes(CANCELLED_SENTINEL)) {
+ return { category: "fatal", retriable: false, retryAfterMs: null, error: e };
+ }
+ if (e.code === "EMBEDDING_QUOTA_EXHAUSTED") {
+ return {
+ category: "quota",
+ retriable: false,
+ retryAfterMs: e.retryAfterMs ?? null,
+ error: e,
+ };
+ }
+ if (e.code === "EMBEDDING_PROVIDER_TIMEOUT") {
+ return { category: "transient", retriable: true, retryAfterMs: null, error: e };
+ }
+ if (e.code === "EMBEDDING_PROVIDER_HTTP") {
+ const status = e.status;
+ const retryAfterMs = e.retryAfterMs ?? null;
+ if (status !== undefined) {
+ if (AUTH_STATUSES.has(status)) {
+ return { category: "auth", retriable: false, retryAfterMs, error: e };
+ }
+ if (status === RATE_LIMIT_STATUS) {
+ return { category: "rate_limit", retriable: true, retryAfterMs, error: e };
+ }
+ if (RETRYABLE_STATUSES.has(status)) {
+ // 429 is handled above, so the remaining retryable statuses are 5xx.
+ return { category: "transient", retriable: true, retryAfterMs, error: e };
+ }
+ // Any other explicit HTTP status (e.g. 400) fails fast.
+ return { category: "fatal", retriable: false, retryAfterMs, error: e };
+ }
+ // No status attached = network error: retry as transient.
+ return { category: "transient", retriable: true, retryAfterMs, error: e };
+ }
+ return { category: "fatal", retriable: false, retryAfterMs: null, error: e };
+ }
+ return {
+ category: "fatal",
+ retriable: false,
+ retryAfterMs: null,
+ error: new SearchError("EMBEDDING_PROVIDER_HTTP", String(e)),
+ };
+}
+
interface OpenAiEmbeddingResponse {
readonly data: ReadonlyArray<{
readonly embedding: ReadonlyArray<number>;
@@ -106,10 +251,23 @@ export class OpenAICompatProvider implements EmbeddingProvider {
return this._dimension;
}
- async embed(texts: ReadonlyArray<string>): Promise<number[][]> {
+ /**
+ * Resolve the instruction prefix for an embed `kind`
+ * (memory-write-path-integrity B2). No kind, or an empty configured prefix,
+ * yields no prefix so the sent text is byte-identical to pre-feature runs.
+ */
+ private prefixFor(kind?: EmbedKind): string {
+ if (kind === "query") return this.config.queryPrefix ?? "";
+ if (kind === "passage") return this.config.passagePrefix ?? "";
+ return "";
+ }
+
+ async embed(texts: ReadonlyArray<string>, kind?: EmbedKind): Promise<number[][]> {
if (texts.length === 0) return [];
+ const prefix = this.prefixFor(kind);
+ const prepared = prefix === "" ? texts : texts.map((t) => prefix + t);
const batches = chunkArray(
- texts.map((t, i) => ({ text: t, originalIndex: i })),
+ prepared.map((t, i) => ({ text: t, originalIndex: i })),
this.config.batchSize,
);
const sem = new Semaphore(this.config.concurrency);
@@ -207,9 +365,9 @@ export class OpenAICompatProvider implements EmbeddingProvider {
}
private isAuthError(e: SearchError): boolean {
- if (e.code !== "EMBEDDING_PROVIDER_HTTP") return false;
- const m = e.message.match(/HTTP (\d+)/);
- return m ? AUTH_STATUSES.has(Number(m[1])) : false;
+ return (
+ e.code === "EMBEDDING_PROVIDER_HTTP" && e.status !== undefined && AUTH_STATUSES.has(e.status)
+ );
}
private async embedBatchOnKey(
@@ -220,19 +378,22 @@ export class OpenAICompatProvider implements EmbeddingProvider {
let lastError: SearchError | null = null;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
if (opts?.parentSignal?.aborted) {
- throw new SearchError("EMBEDDING_PROVIDER_HTTP", "embed cancelled");
+ throw new SearchError("EMBEDDING_PROVIDER_HTTP", CANCELLED_SENTINEL);
}
try {
return await this.embedBatchOnce(texts, opts?.parentSignal);
} catch (e) {
- const err = this.classifyError(e);
- if (!err.retriable || attempt >= maxAttempts) throw err.error;
- lastError = err.error;
+ const cls = classifyEmbeddingError(e);
+ if (!cls.retriable || attempt >= maxAttempts) throw cls.error;
+ lastError = cls.error;
this.retriesSeen++;
- const wait = jittered(
- this.backoffMs[attempt - 1] ?? this.backoffMs[this.backoffMs.length - 1] ?? 4000,
+ const wait = computeRetryDelayMs(
+ cls.retryAfterMs,
+ attempt,
+ this.backoffMs,
+ RETRY_AFTER_CAP_MS,
);
- await sleep(wait);
+ await sleep(wait, opts?.parentSignal);
}
}
throw lastError ?? new SearchError("EMBEDDING_PROVIDER_HTTP", "retry loop exhausted");
@@ -275,7 +436,7 @@ export class OpenAICompatProvider implements EmbeddingProvider {
const cause = e instanceof Error ? e : new Error(String(e));
if (cause.name === "AbortError") {
if (parentSignal?.aborted) {
- throw new SearchError("EMBEDDING_PROVIDER_HTTP", "embed cancelled");
+ throw new SearchError("EMBEDDING_PROVIDER_HTTP", CANCELLED_SENTINEL);
}
throw new SearchError(
"EMBEDDING_PROVIDER_TIMEOUT",
@@ -290,10 +451,23 @@ export class OpenAICompatProvider implements EmbeddingProvider {
if (!response.ok) {
const body = await response.text().catch(() => "");
- const head = body.slice(0, 300);
+ const head = body.slice(0, ERROR_BODY_HEAD_LEN);
+ const status = response.status;
+ const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after")) ?? undefined;
+ const parsed = safeParseJson(body);
+ const isQuota =
+ status === PAYMENT_REQUIRED_STATUS ||
+ (status === RATE_LIMIT_STATUS && bodyHasQuotaEvidence(parsed));
+ if (isQuota) {
+ throw new SearchError("EMBEDDING_QUOTA_EXHAUSTED", EMBEDDING_QUOTA_MESSAGE, {
+ status,
+ retryAfterMs,
+ });
+ }
throw new SearchError(
"EMBEDDING_PROVIDER_HTTP",
- `embedding HTTP ${response.status}: ${head || response.statusText}`,
+ `embedding HTTP ${status}: ${head || response.statusText}`,
+ { status, retryAfterMs },
);
}
@@ -347,32 +521,4 @@ export class OpenAICompatProvider implements EmbeddingProvider {
}
return ordered;
}
-
- private classifyError(e: unknown): { retriable: boolean; error: SearchError } {
- if (e instanceof SearchError) {
- // Parent-cancelled batches surface as a synthetic
- // EMBEDDING_PROVIDER_HTTP "embed cancelled". Retrying them would
- // race against the abort and re-spend budget on a batch the
- // outer Promise already gave up on.
- if (e.message.includes("embed cancelled")) {
- return { retriable: false, error: e };
- }
- if (e.code === "EMBEDDING_PROVIDER_TIMEOUT") return { retriable: true, error: e };
- if (e.code === "EMBEDDING_PROVIDER_HTTP") {
- // Parse status from message if present.
- const m = e.message.match(/HTTP (\d+)/);
- if (m) {
- const status = Number(m[1]);
- return { retriable: RETRYABLE_STATUSES.has(status), error: e };
- }
- // Network errors fall here — retriable.
- return { retriable: true, error: e };
- }
- return { retriable: false, error: e };
- }
- return {
- retriable: false,
- error: new SearchError("EMBEDDING_PROVIDER_HTTP", String(e)),
- };
- }
}
diff --git a/src/core/search/embeddings/presets.ts b/src/core/search/embeddings/presets.ts
index 6c9a5196..391466a9 100644
--- a/src/core/search/embeddings/presets.ts
+++ b/src/core/search/embeddings/presets.ts
@@ -15,6 +15,15 @@
* width, useful when setting `embedding_dimension` up front.
*/
+/**
+ * Instruction prefix an e5-family model expects before a search query
+ * (memory-write-path-integrity B2). Trailing space is intentional: the model
+ * was trained on `"query: <text>"`.
+ */
+export const E5_QUERY_PREFIX = "query: ";
+/** Instruction prefix an e5-family model expects before an indexed passage. */
+export const E5_PASSAGE_PREFIX = "passage: ";
+
/** One curated embedding model the registration flow can recommend. */
export interface EmbeddingModelPreset {
/** Model string sent to the endpoint (`embedding_model` / profile defaultModel). */
@@ -27,6 +36,15 @@ export interface EmbeddingModelPreset {
readonly multilingual: boolean;
/** One-line guidance shown alongside the model. */
readonly note: string;
+ /**
+ * Instruction prefix for a search query (memory-write-path-integrity B2).
+ * Present only for models trained with asymmetric instructions (e5). The
+ * configured `embedding_prefix_query` overrides it; an explicit empty
+ * string disables it.
+ */
+ readonly queryPrefix?: string;
+ /** Instruction prefix for an indexed passage; see {@link queryPrefix}. */
+ readonly passagePrefix?: string;
}
/**
@@ -42,6 +60,8 @@ export const EMBEDDING_MODEL_PRESETS: ReadonlyArray<EmbeddingModelPreset> = Obje
dimension: 384,
multilingual: true,
note: "Small, fast, strong multilingual default. Prefix inputs with 'query:'/'passage:'.",
+ queryPrefix: E5_QUERY_PREFIX,
+ passagePrefix: E5_PASSAGE_PREFIX,
},
{
model: "BAAI/bge-m3",
@@ -87,3 +107,44 @@ export const RECOMMENDED_EMBEDDING_MODEL: string = EMBEDDING_MODEL_PRESETS[0]!.m
export function findEmbeddingPreset(model: string): EmbeddingModelPreset | null {
return EMBEDDING_MODEL_PRESETS.find((p) => p.model === model) ?? null;
}
+
+/**
+ * Structural e5-family detection (memory-write-path-integrity B2). Matches the
+ * `e5` token wherever it appears delimited by `/` or `-` in the model id
+ * (`intfloat/e5-large-v2`, `intfloat/multilingual-e5-small`), so a custom e5
+ * model string not in the curated catalog still gets the instruction-prefix
+ * defaults. Keys off the model id structure, never the prose note.
+ */
+export function isE5FamilyModel(model: string | null): boolean {
+ if (!model) return false;
+ return /(^|[/-])e5([/-]|$)/i.test(model);
+}
+
+/** The prefix pair active for an embed run, after preset + config resolution. */
+export interface ResolvedEmbeddingPrefixes {
+ readonly queryPrefix: string;
+ readonly passagePrefix: string;
+}
+
+/**
+ * Resolve the active query/passage instruction prefixes
+ * (memory-write-path-integrity B2). Precedence per kind: an explicit config
+ * override (including an empty string, which disables the prefix) wins;
+ * otherwise the curated preset field; otherwise the structural e5 default;
+ * otherwise no prefix. A `null` override means "not configured" and falls
+ * through; an empty-string override means "explicitly disabled".
+ */
+export function resolveEmbeddingPrefixes(
+ model: string | null,
+ queryOverride: string | null,
+ passageOverride: string | null,
+): ResolvedEmbeddingPrefixes {
+ const preset = model ? findEmbeddingPreset(model) : null;
+ const e5 = isE5FamilyModel(model);
+ const queryDefault = preset?.queryPrefix ?? (e5 ? E5_QUERY_PREFIX : "");
+ const passageDefault = preset?.passagePrefix ?? (e5 ? E5_PASSAGE_PREFIX : "");
+ return {
+ queryPrefix: queryOverride ?? queryDefault,
+ passagePrefix: passageOverride ?? passageDefault,
+ };
+}
diff --git a/src/core/search/index.ts b/src/core/search/index.ts
index 36279882..15c8491f 100644
--- a/src/core/search/index.ts
+++ b/src/core/search/index.ts
@@ -19,6 +19,7 @@ import {
type ExpandedProvider,
} from "./embeddings/registry.ts";
import { loadRerankRegistry, expandRegisteredRerankProvider } from "./rerank/registry.ts";
+import { resolveEmbeddingPrefixes } from "./embeddings/presets.ts";
import { SearchError } from "./types.ts";
import type {
ResolvedEmbeddingConfig,
@@ -59,7 +60,7 @@ export type {
StructuredRecallQueryDocument,
VaultIgnoreRule,
} from "./types.ts";
-export { SearchError, SEARCH_ERROR_CODES } from "./types.ts";
+export { EMBEDDING_QUOTA_MESSAGE, SearchError, SEARCH_ERROR_CODES } from "./types.ts";
export {
parseStructuredRecallQueryDocument,
structuredRecallQueryText,
@@ -223,6 +224,26 @@ function parseNonNegativeFloat(raw: string | null, fallback: number, fieldName:
return n;
}
+/**
+ * Raw setting lookup that preserves an explicit empty string
+ * (memory-write-path-integrity B2). Unlike `envOrConfig`, which folds `""`
+ * into "unset", this returns `""` when a key is present-but-empty so an
+ * operator can explicitly DISABLE a preset-provided default; only a truly
+ * absent key returns null.
+ */
+function rawSetting(
+ env: NodeJS.ProcessEnv,
+ config: Readonly<Record<string, string>>,
+ envKey: string,
+ configKey: string,
+): string | null {
+ const e = env[envKey];
+ if (e !== undefined) return e;
+ const c = config[configKey];
+ if (c !== undefined) return c;
+ return null;
+}
+
/**
* Parse a finite float over the whole real line (e.g. a rerank floor,
* which can be negative for backends that emit logits rather than [0, 1]
@@ -475,6 +496,21 @@ export function resolveSearchConfig(opts: {
"embedding_cost_gate_usd",
);
+ // Instruction prefixes (memory-write-path-integrity B2). Resolved with raw
+ // presence, not `envOrConfig`, because an explicit empty string must DISABLE
+ // a preset prefix rather than fall through to the default. An absent key
+ // (null) falls through to the preset / structural e5 default.
+ const { queryPrefix, passagePrefix } = resolveEmbeddingPrefixes(
+ model,
+ rawSetting(env, config, "OPEN_SECOND_BRAIN_EMBEDDING_PREFIX_QUERY", "embedding_prefix_query"),
+ rawSetting(
+ env,
+ config,
+ "OPEN_SECOND_BRAIN_EMBEDDING_PREFIX_PASSAGE",
+ "embedding_prefix_passage",
+ ),
+ );
+
const semantic: ResolvedEmbeddingConfig = Object.freeze({
enabled: semanticEnabled,
provider,
@@ -488,6 +524,8 @@ export function resolveSearchConfig(opts: {
batchSize,
maxRetries,
costGateUsd,
+ queryPrefix,
+ passagePrefix,
});
// Cross-encoder rerank (retrieval-precision-quality-loop, card A). Off
diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.ts
index bf98a97b..1d27773c 100644
--- a/src/core/search/indexer.ts
+++ b/src/core/search/indexer.ts
@@ -46,7 +46,12 @@ import { parseFrontmatterText } from "../vault.ts";
import { appendMetric } from "../brain/metrics.ts";
import { throwIfAborted } from "../brain/safeguard.ts";
import { extractEntities } from "./entities.ts";
-import { acquireWriterLock, Store } from "./store.ts";
+import {
+ acquireWriterLock,
+ Store,
+ EMBEDDING_PREFIX_QUERY_STATE_KEY,
+ EMBEDDING_PREFIX_PASSAGE_STATE_KEY,
+} from "./store.ts";
import { LATEST_SCHEMA_VERSION } from "./schema.ts";
import { SearchError } from "./types.ts";
import { walkVault } from "./walker.ts";
@@ -598,7 +603,7 @@ async function populateEmbeddings(
throwIfAborted(signal, "index");
const batch = pending.slice(i, i + superBatch);
const texts = batch.map((p) => p.content);
- const vectors = await provider.embed(texts);
+ const vectors = await provider.embed(texts, "passage");
stats.embeddingsRetries += provider.consumeRetryCount?.() ?? 0;
if (vectors.length !== batch.length) {
throw new SearchError(
@@ -614,7 +619,10 @@ async function populateEmbeddings(
"provider returned vectors of zero length",
);
}
- store.ensureEmbeddingModel(model, dim);
+ store.ensureEmbeddingModel(model, dim, {
+ query: config.semantic.queryPrefix ?? "",
+ passage: config.semantic.passagePrefix ?? "",
+ });
for (let j = 0; j < batch.length; j++) {
const chunkId = batch[j]!.chunkId;
const vec = vectors[j]!;
@@ -826,6 +834,25 @@ export async function indexStatus(config: ResolvedSearchConfig): Promise<IndexSt
warnings.push("embedding_api_key not configured; semantic search disabled");
}
+ // Instruction-prefix drift (memory-write-path-integrity B2). Stored
+ // vectors were embedded under the prefix pair recorded at index time; if
+ // the configured pair now differs they are not comparable to prefixed
+ // queries, so surface the reindex-required warning. A stored null is a
+ // pre-feature (unprefixed) index, compared as the empty pair.
+ if (config.semantic.enabled && counts.embeddings > 0) {
+ const storedQuery = store.getState(EMBEDDING_PREFIX_QUERY_STATE_KEY) ?? "";
+ const storedPassage = store.getState(EMBEDDING_PREFIX_PASSAGE_STATE_KEY) ?? "";
+ const configuredQuery = config.semantic.queryPrefix ?? "";
+ const configuredPassage = config.semantic.passagePrefix ?? "";
+ if (storedQuery !== configuredQuery || storedPassage !== configuredPassage) {
+ warnings.push(
+ "embedding instruction prefixes changed since the last index run " +
+ `(stored [${storedQuery}|${storedPassage}], configured ` +
+ `[${configuredQuery}|${configuredPassage}]); run: o2b search reindex --embeddings`,
+ );
+ }
+ }
+
// Best-effort spend estimate to bring stale/missing embeddings current.
// Only scan chunk content when the active model is actually priced.
const activeModel =
diff --git a/src/core/search/semantic-phase.ts b/src/core/search/semantic-phase.ts
index cb48a114..89d89ae8 100644
--- a/src/core/search/semantic-phase.ts
+++ b/src/core/search/semantic-phase.ts
@@ -5,9 +5,10 @@
* to keyword-only with warnings when the lane cannot run).
*/
+import { classifyEmbeddingError } from "./embeddings/openai-compat.ts";
import { makeProvider } from "./embeddings/provider.ts";
import { Store } from "./store.ts";
-import { SearchError } from "./types.ts";
+import { EMBEDDING_QUOTA_MESSAGE, SearchError } from "./types.ts";
import type { ResolvedSearchConfig, SearchOptions } from "./types.ts";
export interface SemanticPolicy {
@@ -91,7 +92,7 @@ export async function runSemanticPhase(
let queryVec: number[];
try {
const provider = makeProvider(config.semantic);
- const vectors = await provider.embed([query]);
+ const vectors = await provider.embed([query], "query");
queryVec = vectors[0] ?? [];
} catch (e) {
if (opts.explicit) {
@@ -102,8 +103,18 @@ export async function runSemanticPhase(
const msg = e instanceof Error ? e.message : String(e);
throw new SearchError("EMBEDDING_PROVIDER_HTTP", `embedding provider failure: ${msg}`);
}
- const msg = e instanceof Error ? e.message : String(e);
- warnings.push(`embedding provider unavailable: ${msg}`);
+ // Implicit path: degrade to keyword-only, but the warning must say WHY
+ // by naming the classification category, and for a quota exhaustion it
+ // carries the actionable billing message so the CLI/MCP caller learns
+ // the remediation, not just that semantic was skipped.
+ const cls = classifyEmbeddingError(e);
+ const detail =
+ cls.category === "quota"
+ ? EMBEDDING_QUOTA_MESSAGE
+ : e instanceof Error
+ ? e.message
+ : String(e);
+ warnings.push(`embedding provider unavailable [${cls.category}]: ${detail}`);
return { attempted: false, hits: [], warnings };
}
diff --git a/src/core/search/store.ts b/src/core/search/store.ts
index 6a0d1964..8f03562a 100644
--- a/src/core/search/store.ts
+++ b/src/core/search/store.ts
@@ -23,6 +23,7 @@ import { registerWriterDb, unregisterWriterDb } from "./store-exit.ts";
import { computeCorpusGeneration } from "./corpus-generation.ts";
import { SearchError } from "./types.ts";
import type { ResolvedSearchConfig } from "./types.ts";
+import { assertValidVector } from "./vector-guard.ts";
import {
applyMigrations,
documentBasename,
@@ -36,6 +37,22 @@ import {
// Types
// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * `index_state` keys for the active embedding instruction prefixes
+ * (memory-write-path-integrity B2). Recorded per index run so a later
+ * stored-vs-configured mismatch can surface the reindex-required warning:
+ * vectors embedded under one prefix pair are not comparable to queries
+ * embedded under another.
+ */
+export const EMBEDDING_PREFIX_QUERY_STATE_KEY = "embedding_prefix_query";
+export const EMBEDDING_PREFIX_PASSAGE_STATE_KEY = "embedding_prefix_passage";
+
+/** The query/passage instruction prefixes active for an index run. */
+export interface EmbeddingPrefixPair {
+ readonly query: string;
+ readonly passage: string;
+}
+
export interface StoreOpenOptions {
/** "read" never locks; "write" acquires an exclusive proper-lockfile. */
readonly mode: "read" | "write";
@@ -436,7 +453,10 @@ export class Store {
ensureFts5(db);
const vecLoaded = loadVec && tryLoadVecExtension(db);
const store = new Store(db, config, vecLoaded, release);
- store.ensureEmbeddingModel(config.semantic.model, config.semantic.dimension);
+ store.ensureEmbeddingModel(config.semantic.model, config.semantic.dimension, {
+ query: config.semantic.queryPrefix ?? "",
+ passage: config.semantic.passagePrefix ?? "",
+ });
// Belt-and-suspenders: consolidate this writer's WAL on a
// bypassed close (process.exit / signal-driven exit).
registerWriterDb(db);
@@ -838,6 +858,7 @@ export class Store {
`vector dimension ${len} != configured dimension ${dimension}`,
);
}
+ assertValidVector(vector, "vecUpsert");
this.db.exec("BEGIN");
try {
const existing = this.db
@@ -943,7 +964,11 @@ export class Store {
* and both old + new are non-null, drop embeddings + vec table and
* log one line per design §13. First-time set just records state.
*/
- ensureEmbeddingModel(model: string | null, dimension: number | null): ModelChangeOutcome {
+ ensureEmbeddingModel(
+ model: string | null,
+ dimension: number | null,
+ prefixes?: EmbeddingPrefixPair,
+ ): ModelChangeOutcome {
const prevModel = this.getState("embedding_model");
const prevDimRaw = this.getState("embedding_dimension");
const prevDim = prevDimRaw === null ? null : Number(prevDimRaw);
@@ -952,6 +977,24 @@ export class Store {
const dimChanged =
prevDim !== null && dimension !== null && Number.isFinite(prevDim) && prevDim !== dimension;
+ // A prefix change invalidates stored vectors exactly as a model/dimension
+ // change does: vectors embedded under the old prefix are not comparable to
+ // queries embedded under the new one. Reuse the same clear-and-log path.
+ const prevQueryPrefix = this.getState(EMBEDDING_PREFIX_QUERY_STATE_KEY);
+ const prevPassagePrefix = this.getState(EMBEDDING_PREFIX_PASSAGE_STATE_KEY);
+ // Legacy stores predate prefix metadata: absent state (null) means the
+ // existing vectors were embedded with EMPTY prefixes. Treat missing state
+ // as the empty pair so a switch to non-empty prefixes (e.g. E5's
+ // `query:`/`passage:`) is detected as a change and the now-incompatible
+ // unprefixed vectors are cleared, rather than silently marked compatible.
+ const effectivePrevQueryPrefix = prevQueryPrefix ?? "";
+ const effectivePrevPassagePrefix = prevPassagePrefix ?? "";
+ const prefixChanged =
+ prefixes !== undefined &&
+ this.countEmbeddings() > 0 &&
+ (effectivePrevQueryPrefix !== prefixes.query ||
+ effectivePrevPassagePrefix !== prefixes.passage);
+
if (modelChanged || dimChanged) {
this.clearEmbeddings();
// eslint-disable-next-line no-console
@@ -960,10 +1003,22 @@ export class Store {
);
this.deleteState("embedding_model");
this.deleteState("embedding_dimension");
+ } else if (prefixChanged) {
+ // Model/dimension unchanged: the prefix change alone triggers the clear.
+ this.clearEmbeddings();
+ // eslint-disable-next-line no-console
+ console.error(
+ `embedding prefixes changed from [${effectivePrevQueryPrefix}|${effectivePrevPassagePrefix}] ` +
+ `to [${prefixes.query}|${prefixes.passage}], embeddings cleared`,
+ );
}
if (model !== null) this.setState("embedding_model", model);
if (dimension !== null) this.setState("embedding_dimension", String(dimension));
+ if (prefixes !== undefined) {
+ this.setState(EMBEDDING_PREFIX_QUERY_STATE_KEY, prefixes.query);
+ this.setState(EMBEDDING_PREFIX_PASSAGE_STATE_KEY, prefixes.passage);
+ }
// (Re)create vec table when we know the dimension and vec is loaded.
if (this._vecLoaded && dimension !== null) {
@@ -1650,6 +1705,7 @@ export class Store {
const limit = Math.max(1, opts.limit | 0);
const prefix = opts.pathPrefix && opts.pathPrefix.length > 0 ? opts.pathPrefix : null;
+ assertValidVector(queryVector, "semanticTopK");
const buf = vecToBuffer(queryVector);
if (prefix) {
const rows = this.db
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index bdd537d8..2dc24eea 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -18,19 +18,56 @@ export const SEARCH_ERROR_CODES = [
"EMBEDDING_PROVIDER_HTTP",
"EMBEDDING_PROVIDER_TIMEOUT",
"EMBEDDING_DIMENSION_MISMATCH",
+ "EMBEDDING_INVALID_VECTOR",
"EMBEDDING_COST_GATE",
+ "EMBEDDING_QUOTA_EXHAUSTED",
"RERANK_PROVIDER_HTTP",
"INDEX_LOCKED",
"INVALID_INPUT",
] as const;
export type SearchErrorCode = (typeof SEARCH_ERROR_CODES)[number];
+/**
+ * Actionable operator-facing message for an exhausted embedding quota /
+ * billing limit (Task C1/C2). Shared by the provider (thrown message), the
+ * semantic-phase degrade warning, and the MCP error mapping so the single
+ * remediation instruction stays consistent across every surface.
+ */
+export const EMBEDDING_QUOTA_MESSAGE =
+ "embedding quota/billing exhausted: semantic search is degraded to keyword-only. " +
+ "Check your embedding provider billing and quota, raise the limit or top up, then reindex.";
+
+/**
+ * Coarse outcome category for an embedding-provider error (Task C1). Drives
+ * both the retry policy (`retriable`) and the degrade-warning wording.
+ * `quota` and `auth` fail fast; `rate_limit` and `transient` retry.
+ */
+export type EmbeddingErrorCategory = "quota" | "rate_limit" | "auth" | "transient" | "fatal";
+
+/**
+ * Additive structured context for a {@link SearchError} originating from a
+ * provider HTTP response. Both fields are optional so every existing
+ * two-argument call site stays valid.
+ */
+export interface SearchErrorOptions {
+ /** Upstream HTTP status code. */
+ readonly status?: number;
+ /** Parsed `Retry-After` delay in milliseconds. */
+ readonly retryAfterMs?: number;
+}
+
export class SearchError extends Error {
readonly code: SearchErrorCode;
- constructor(code: SearchErrorCode, message: string) {
+ /** Upstream HTTP status when this error originated from a provider response. */
+ readonly status?: number;
+ /** Parsed `Retry-After` delay in milliseconds when the provider supplied one. */
+ readonly retryAfterMs?: number;
+ constructor(code: SearchErrorCode, message: string, opts?: SearchErrorOptions) {
super(message);
this.name = "SearchError";
this.code = code;
+ if (opts?.status !== undefined) this.status = opts.status;
+ if (opts?.retryAfterMs !== undefined) this.retryAfterMs = opts.retryAfterMs;
}
}
@@ -712,6 +749,17 @@ export interface ResolvedEmbeddingConfig {
* run whose estimated cost exceeds this is refused unless forced.
*/
readonly costGateUsd: number;
+ /**
+ * Active instruction prefix for a search query
+ * (memory-write-path-integrity B2). Resolved from the preset default and
+ * the `embedding_prefix_query` config/env override; an empty string means
+ * no prefix (byte-identical to pre-feature behaviour). Optional so every
+ * existing config literal stays valid; the openai-compat provider treats
+ * an absent value as empty.
+ */
+ readonly queryPrefix?: string;
+ /** Active instruction prefix for an indexed passage; see {@link queryPrefix}. */
+ readonly passagePrefix?: string;
}
/**
diff --git a/src/core/search/vector-guard.ts b/src/core/search/vector-guard.ts
new file mode 100644
index 00000000..f5480fdb
--- /dev/null
+++ b/src/core/search/vector-guard.ts
@@ -0,0 +1,44 @@
+/**
+ * Vector validity kernel (memory-write-path-integrity B1). A single
+ * choke-point guard shared by the store write path (`vecUpsert`), the store
+ * query path (`semanticTopK`), and provider normalisation
+ * (`unitNormaliseInPlace`). A NaN/Infinity component silently poisons every
+ * cosine distance it participates in, and an all-zero vector has no direction
+ * at all - both are exactly the misleading no-op inputs this project forbids,
+ * so they surface as a typed, actionable {@link SearchError} instead of
+ * reaching the vec table or degrading ranking silently.
+ */
+
+import { SearchError } from "./types.ts";
+
+/**
+ * Throw {@link SearchError} `EMBEDDING_INVALID_VECTOR` when `vector` is empty,
+ * carries a non-finite component (NaN/Infinity), or is all zeros. The message
+ * names `context` (e.g. "vecUpsert", "semanticTopK", "unitNormalise") and the
+ * offending index/reason so the failure is actionable at the call site.
+ */
+export function assertValidVector(
+ vector: ReadonlyArray<number> | Float32Array,
+ context: string,
+): void {
+ if (vector.length === 0) {
+ throw new SearchError("EMBEDDING_INVALID_VECTOR", `${context}: embedding vector is empty`);
+ }
+ let allZero = true;
+ for (let index = 0; index < vector.length; index++) {
+ const value = vector[index] as number;
+ if (!Number.isFinite(value)) {
+ throw new SearchError(
+ "EMBEDDING_INVALID_VECTOR",
+ `${context}: embedding vector has non-finite value ${value} at index ${index}`,
+ );
+ }
+ if (value !== 0) allZero = false;
+ }
+ if (allZero) {
+ throw new SearchError(
+ "EMBEDDING_INVALID_VECTOR",
+ `${context}: embedding vector is all zeros (no direction for cosine similarity)`,
+ );
+ }
+}
diff --git a/src/mcp/brain/feedback-tools.ts b/src/mcp/brain/feedback-tools.ts
index b262a547..e2663a17 100644
--- a/src/mcp/brain/feedback-tools.ts
+++ b/src/mcp/brain/feedback-tools.ts
@@ -23,6 +23,10 @@ import {
} from "../../core/brain/dream-stage.ts";
import { BRAIN_ROLES } from "../../core/brain/trust/role.ts";
import { resolveEffectiveScope, writeSignal } from "../../core/brain/signal.ts";
+import {
+ adviseIncomingFeedback,
+ type WriteConflictAdvisory,
+} from "../../core/brain/write-advisory.ts";
import { loadFeedbackDefaultScopeSafe } from "../../core/brain/policy.ts";
import { writePreference } from "../../core/brain/preference.ts";
import { validateBrainFeedbackInput } from "../../core/brain/sessions/validate-feedback.ts";
@@ -177,6 +181,18 @@ async function toolBrainFeedback(
process.stderr.write(`warning: append feedback log failed: ${(err as Error).message}\n`);
}
+ // Write-time conflict advisory (A4): compare the incoming principle
+ // against confirmed same-scope preferences and surface a non-blocking
+ // advisory when it closely resembles an existing rule. Computed BEFORE
+ // any force-confirmed write so it never matches the pref this very call
+ // is about to create. The write has already landed; this never blocks it.
+ const advisory: WriteConflictAdvisory | null = adviseIncomingFeedback(ctx.vault, {
+ principle,
+ ...(effectiveScope !== undefined ? { scope: effectiveScope } : {}),
+ agent,
+ now,
+ });
+
let prefResult: { path: string; id: string } | null = null;
if (forceConfirmed) {
// Escape hatch: skip the dream pass and create the confirmed rule now.
@@ -216,6 +232,7 @@ async function toolBrainFeedback(
return {
kind: prefResult ? "preference" : "signal",
...(mirror !== undefined ? { mirror } : {}),
+ ...(advisory !== null ? { advisory } : {}),
signal_path: vaultRelativeSafe(ctx.vault, sigResult.path),
signal_absolute_path: resolve(sigResult.path),
signal_id: sigResult.id,
diff --git a/src/mcp/brain/ingest-tools.ts b/src/mcp/brain/ingest-tools.ts
index 072cab2d..d75bd8d2 100644
--- a/src/mcp/brain/ingest-tools.ts
+++ b/src/mcp/brain/ingest-tools.ts
@@ -92,6 +92,10 @@ function serializePlan(plan: SourceCleanupPlan): Record<string, unknown> {
deleted: [...plan.deleted],
manifest_entry_removed: plan.manifestEntryRemoved,
audit_record_id: plan.auditRecordId,
+ // The D1 recovery point. Only the run id is surfaced here (not the
+ // absolute archive path) so the response stays free of host paths; the
+ // archive lives at the deterministic `Brain/.snapshots/<run_id>.tar.zst`.
+ snapshot_run_id: plan.snapshotRunId,
};
}
diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.ts
index f729ed19..2d633544 100644
--- a/src/mcp/search-tools.ts
+++ b/src/mcp/search-tools.ts
@@ -12,6 +12,7 @@
import {
captureRecallFeedback,
+ EMBEDDING_QUOTA_MESSAGE,
evaluateSurfacingGate,
expandHit,
indexStatus,
@@ -397,8 +398,11 @@ function truncateContent(c: string, max: number): string {
return c.slice(0, max - 1) + "…";
}
-function searchErrorToMcp(e: SearchError): MCPError {
+export function searchErrorToMcp(e: SearchError): MCPError {
if (e.code === "INVALID_INPUT") return new MCPError(INVALID_PARAMS, e.message);
+ if (e.code === "EMBEDDING_QUOTA_EXHAUSTED") {
+ return new MCPError(INTERNAL_ERROR, EMBEDDING_QUOTA_MESSAGE);
+ }
if (e.code === "INDEX_MISSING") {
return new MCPError(INTERNAL_ERROR, "search index not initialised. Run: o2b search index");
}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 124c4fa8..62823f58 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -21,7 +21,12 @@
* only assembles them in a stable order and applies scope filtering.
*/
-import { discoverConfig, redactMapping } from "../core/config.ts";
+import {
+ discoverConfig,
+ redactMapping,
+ resolveExposeHostPaths,
+ vaultStoreReference,
+} from "../core/config.ts";
import { REMOVED_TOOLS } from "../core/removed-surfaces.ts";
import { computeBrainStatus } from "../core/brain/status.ts";
import { doctor } from "../core/doctor.ts";
@@ -69,6 +74,20 @@ function vaultRelpath(target: string, vault: string): string {
}
}
+/**
+ * The `vault_path` field for an MCP response. By default this is the
+ * opaque, stable store reference (`vault://<hex>`) rather than the
+ * absolute host path, since MCP responses land in model context. The
+ * `expose_host_paths` config escape hatch restores the raw path for
+ * operators whose tooling depends on it (D2).
+ */
+function vaultPathField(ctx: ServerContext): string {
+ const configPath = ctx.configPath ?? undefined;
+ return resolveExposeHostPaths(configPath)
+ ? ctx.vault
+ : vaultStoreReference(ctx.vault, configPath);
+}
+
// ── Tool implementations ────────────────────────────────────────────────────
async function toolStatus(ctx: ServerContext): Promise<Record<string, unknown>> {
@@ -114,7 +133,7 @@ async function toolStatus(ctx: ServerContext): Promise<Record<string, unknown>>
config_exists: discovery.exists,
config_keys: configKeys,
config: redactMapping(discovery.data),
- vault_path: ctx.vault,
+ vault_path: vaultPathField(ctx),
vault_exists: vaultExists,
...(vault ? { vault } : {}),
...(brain ? { brain } : {}),
@@ -145,7 +164,7 @@ async function toolQuery(
if (matched.length >= limit) break;
}
return {
- vault_path: ctx.vault,
+ vault_path: vaultPathField(ctx),
total_pages: pages.length,
returned: matched.length,
limit,
@@ -178,7 +197,7 @@ async function toolVaultHealth(
}).map((n) => ({ code: n.code, severity: n.severity, message: n.message }));
return {
- vault_path: ctx.vault,
+ vault_path: vaultPathField(ctx),
config_path: ctx.configPath ? String(ctx.configPath) : null,
repo_root: repoRoot ? String(repoRoot) : null,
ok: payload.every((c) => c.ok),
diff --git a/tests/cli/brain-entity.test.ts b/tests/cli/brain-entity.test.ts
index 40f90bb9..2c50fded 100644
--- a/tests/cli/brain-entity.test.ts
+++ b/tests/cli/brain-entity.test.ts
@@ -120,4 +120,29 @@ describe("o2b brain entity", () => {
expect(out.returncode).not.toBe(0);
expect(out.stderr).toContain("alias");
});
+
+ test("set strips Markdown decoration from the stored name", async () => {
+ const out = await runCli(["brain", "entity", "set", "projects", "**Mercury**", "--json"], {
+ env: env(),
+ });
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as Record<string, unknown>;
+ expect(payload["name"]).toBe("Mercury");
+ expect(payload["id"]).toBe("ent-projects-mercury");
+ });
+
+ test("set rejects a structurally-junk name with a non-zero exit", async () => {
+ const out = await runCli(["brain", "entity", "set", "people", "***"], { env: env() });
+ expect(out.returncode).not.toBe(0);
+ expect(out.stderr).toContain("invalid entity label");
+ });
+
+ test("prune is dry-run by default and reports no candidates on a clean vault", async () => {
+ await seed();
+ const out = await runCli(["brain", "entity", "prune", "--json"], { env: env() });
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as { confirmed: boolean; candidates: unknown[] };
+ expect(payload.confirmed).toBe(false);
+ expect(payload.candidates).toEqual([]);
+ });
});
diff --git a/tests/cli/brain-feedback-advisory.test.ts b/tests/cli/brain-feedback-advisory.test.ts
new file mode 100644
index 00000000..39554917
--- /dev/null
+++ b/tests/cli/brain-feedback-advisory.test.ts
@@ -0,0 +1,109 @@
+/**
+ * A4 (t_f79b4fe0): CLI surface for the write-time conflict advisory.
+ *
+ * `o2b brain feedback` records the signal as before, and additionally
+ * surfaces a non-blocking advisory when the incoming principle resembles a
+ * confirmed same-scope preference. The write always proceeds regardless.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-feedback-advisory-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
+
+async function seedConfirmed(principle: string, scope: string): Promise<void> {
+ const out = await runCli(
+ [
+ "brain",
+ "feedback",
+ "--topic",
+ "tabs-rule",
+ "--signal",
+ "positive",
+ "--principle",
+ principle,
+ "--scope",
+ scope,
+ "--force-confirmed",
+ ],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(0);
+}
+
+describe("o2b brain feedback - write-conflict advisory", () => {
+ test("surfaces the advisory when the incoming principle resembles a confirmed same-scope preference", async () => {
+ await seedConfirmed("always indent source with tabs not spaces", "coding");
+ const out = await runCli(
+ [
+ "brain",
+ "feedback",
+ "--topic",
+ "tabs-again",
+ "--signal",
+ "negative",
+ "--principle",
+ "always indent source with tabs not spaces",
+ "--scope",
+ "coding",
+ "--json",
+ ],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as {
+ signal_id: string;
+ advisory?: { scope: string | null; conflicts: Array<{ pref_id: string; jaccard: number }> };
+ };
+ // The write proceeded.
+ expect(payload.signal_id).toMatch(/^sig-/);
+ // The advisory names the confirmed preference.
+ expect(payload.advisory).toBeDefined();
+ expect(payload.advisory!.conflicts.map((c) => c.pref_id)).toContain("pref-tabs-rule");
+ });
+
+ test("no advisory for a non-conflicting principle; the write still proceeds", async () => {
+ await seedConfirmed("always indent source with tabs not spaces", "coding");
+ const out = await runCli(
+ [
+ "brain",
+ "feedback",
+ "--topic",
+ "semantic-html",
+ "--signal",
+ "positive",
+ "--principle",
+ "prefer semantic HTML over generic containers",
+ "--scope",
+ "coding",
+ "--json",
+ ],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as { signal_id: string; advisory?: unknown };
+ expect(payload.signal_id).toMatch(/^sig-/);
+ expect(payload.advisory).toBeUndefined();
+ });
+});
diff --git a/tests/cli/brain-pending.test.ts b/tests/cli/brain-pending.test.ts
new file mode 100644
index 00000000..30c65185
--- /dev/null
+++ b/tests/cli/brain-pending.test.ts
@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { stagePendingSignal } from "../../src/core/brain/pending.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-pending-cli-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
+
+function stage(slug: string): string {
+ const res = stagePendingSignal(vault, {
+ topic: slug,
+ signal: "positive",
+ agent: "test-agent",
+ principle: `https://${slug}.dev`,
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug,
+ source_type: "extracted",
+ dedup_hash: `hash-${slug}`,
+ });
+ return res.id;
+}
+
+function inboxNames(): string[] {
+ return readdirSync(brainDirs(vault).inbox).filter((f) => f.startsWith("sig-"));
+}
+
+describe("o2b brain pending", () => {
+ test("list --json reports the staged queue", async () => {
+ const id = stage("fact-url");
+ const out = await runCli(["brain", "pending", "list", "--json"], { env: env() });
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as { pending: Array<{ id: string }>; total: number };
+ expect(payload.total).toBe(1);
+ expect(payload.pending[0]!.id).toBe(id);
+ });
+
+ test("apply moves a staged signal into the inbox", async () => {
+ const id = stage("fact-url");
+ const out = await runCli(["brain", "pending", "apply", id], { env: env() });
+ expect(out.returncode).toBe(0);
+ expect(out.stdout).toContain(`applied: ${id}`);
+ expect(inboxNames()).toContain(`${id}.md`);
+ expect(existsSync(join(brainDirs(vault).pending, `${id}.md`))).toBe(false);
+ });
+
+ test("reject moves a staged signal to retired with a reason", async () => {
+ const id = stage("fact-url");
+ const out = await runCli(
+ ["brain", "pending", "reject", id, "--reason", "not useful", "--json"],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as { status: string; reason: string };
+ expect(payload.status).toBe("rejected");
+ expect(payload.reason).toBe("not useful");
+ expect(existsSync(join(brainDirs(vault).retired, `${id}.md`))).toBe(true);
+ });
+
+ test("apply of a missing id exits 2 (typed error, not a no-op)", async () => {
+ const out = await runCli(["brain", "pending", "apply", "sig-2026-07-18-nope"], {
+ env: env(),
+ });
+ expect(out.returncode).toBe(2);
+ expect(out.stderr).toContain("pending signal not found");
+ });
+
+ test("reject without --reason is a usage error", async () => {
+ const id = stage("fact-url");
+ const out = await runCli(["brain", "pending", "reject", id], { env: env() });
+ expect(out.returncode).not.toBe(0);
+ });
+
+ test("list on an empty queue reports nothing", async () => {
+ const out = await runCli(["brain", "pending", "list"], { env: env() });
+ expect(out.returncode).toBe(0);
+ expect(out.stdout).toContain("no pending signals");
+ });
+});
diff --git a/tests/cli/brain-signal-retire.test.ts b/tests/cli/brain-signal-retire.test.ts
new file mode 100644
index 00000000..ca819204
--- /dev/null
+++ b/tests/cli/brain-signal-retire.test.ts
@@ -0,0 +1,82 @@
+/**
+ * A5 (t_66c12a67): CLI surface for the fact signal retire lifecycle.
+ *
+ * `o2b brain signal retire <id> --reason <text> [--superseded-by <id>]`
+ * moves an inbox signal into Brain/retired/. A missing / already-retired /
+ * non-signal id exits 2 (never a silent no-op).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { writeSignal } from "../../src/core/brain/signal.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-signal-retire-cli-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
+
+function seed(slug: string): string {
+ const res = writeSignal(vault, {
+ topic: slug,
+ signal: "positive",
+ agent: "test-agent",
+ principle: `https://${slug}.dev`,
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug,
+ source_type: "extracted",
+ dedup_hash: `hash-${slug}`,
+ });
+ return res.id;
+}
+
+describe("o2b brain signal retire", () => {
+ test("retire moves an inbox signal into retired/", async () => {
+ const id = seed("fact-url");
+ const out = await runCli(
+ ["brain", "signal", "retire", id, "--reason", "no longer relevant", "--json"],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(0);
+ const payload = JSON.parse(out.stdout) as { id: string; path: string; status: string };
+ expect(payload.id).toBe(id);
+ expect(payload.status).toBe("retired");
+ expect(existsSync(join(brainDirs(vault).inbox, `${id}.md`))).toBe(false);
+ expect(existsSync(join(brainDirs(vault).retired, `${id}.md`))).toBe(true);
+ });
+
+ test("missing --reason exits non-zero without moving anything", async () => {
+ const id = seed("fact-url");
+ const out = await runCli(["brain", "signal", "retire", id], { env: env() });
+ expect(out.returncode).not.toBe(0);
+ expect(existsSync(join(brainDirs(vault).inbox, `${id}.md`))).toBe(true);
+ expect(existsSync(join(brainDirs(vault).retired, `${id}.md`))).toBe(false);
+ });
+
+ test("a missing id exits 2", async () => {
+ const out = await runCli(
+ ["brain", "signal", "retire", "sig-2026-07-18-absent", "--reason", "x"],
+ { env: env() },
+ );
+ expect(out.returncode).toBe(2);
+ });
+});
diff --git a/tests/core/brain.types.test.ts b/tests/core/brain.types.test.ts
index 95864e98..04572808 100644
--- a/tests/core/brain.types.test.ts
+++ b/tests/core/brain.types.test.ts
@@ -87,8 +87,16 @@ describe("BRAIN_* const enums", () => {
"session-lifecycle",
// Agent Write Contract Suite (v0.41.0) terminal write-session audit
"write-session",
+ // A1 (t_657b365e) entity-label quality gate anchoring skip
+ "entity-anchor-skip",
// today-operator-surface (t_d7be2a0c) marker write-back audit
"attribute-write",
+ // A2 (t_375e98fd) durability gate transient-content skip
+ "durability-skip",
+ // A4 (t_f79b4fe0) write-time conflict advisory
+ "write-conflict-advisory",
+ // A5 (t_66c12a67) fact signal retire lifecycle
+ "signal-retire",
]);
const actual = new Set<string>(Object.values(BRAIN_LOG_EVENT_KIND));
expect(actual).toEqual(expected);
diff --git a/tests/core/brain/doctor-symlink-escape.test.ts b/tests/core/brain/doctor-symlink-escape.test.ts
new file mode 100644
index 00000000..79dbeb7c
--- /dev/null
+++ b/tests/core/brain/doctor-symlink-escape.test.ts
@@ -0,0 +1,70 @@
+/**
+ * D2 (t_29a63073): symlink-escape doctor lint.
+ *
+ * A symlink INSIDE Brain/ whose realpath resolves OUTSIDE the vault
+ * root is an exfiltration/clobber hazard: a reader following it leaves
+ * the vault. The doctor reports it as an error-severity `symlink-escape`
+ * issue. It is a lint only - never auto-fixed. A symlink that stays
+ * inside the vault is legitimate and must NOT flag.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runDoctor } from "../../../src/core/brain/doctor.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+
+let tmp: string;
+let vault: string;
+let outside: string;
+let configPath: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-symlink-escape-"));
+ vault = join(tmp, "vault");
+ outside = join(tmp, "outside");
+ mkdirSync(vault, { recursive: true });
+ mkdirSync(outside, { recursive: true });
+ writeFileSync(join(outside, "secret.txt"), "exfiltrate me\n", "utf8");
+ configPath = join(tmp, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("symlink-escape lint", () => {
+ test("flags a Brain/ symlink whose realpath resolves outside the vault", () => {
+ const link = join(brainDirs(vault).inbox, "escape");
+ symlinkSync(outside, link);
+
+ const result = runDoctor(vault);
+ const escape = [...result.errors, ...result.warnings].find((i) => i.code === "symlink-escape");
+ expect(escape).toBeDefined();
+ expect(escape!.severity).toBe("error");
+ expect(escape!.path).toBe("Brain/inbox/escape");
+ });
+
+ test("does NOT flag a Brain/ symlink that stays inside the vault", () => {
+ // A link inside Brain/ pointing at another in-vault path is legitimate.
+ const targetInside = join(brainDirs(vault).preferences);
+ const link = join(brainDirs(vault).inbox, "internal");
+ symlinkSync(targetInside, link);
+
+ const result = runDoctor(vault);
+ const escape = [...result.errors, ...result.warnings].find((i) => i.code === "symlink-escape");
+ expect(escape).toBeUndefined();
+ });
+
+ test("a clean vault with no symlinks reports no symlink-escape", () => {
+ const result = runDoctor(vault);
+ const escape = [...result.errors, ...result.warnings].find((i) => i.code === "symlink-escape");
+ expect(escape).toBeUndefined();
+ });
+});
diff --git a/tests/core/brain/entities.canonical.test.ts b/tests/core/brain/entities.canonical.test.ts
index 52e1d6df..e4d287b8 100644
--- a/tests/core/brain/entities.canonical.test.ts
+++ b/tests/core/brain/entities.canonical.test.ts
@@ -1,9 +1,16 @@
import { describe, expect, test } from "bun:test";
import {
+ ENTITY_LABEL_MAX_LENGTH,
+ InvalidEntityLabelError,
+ assertValidEntityLabel,
entityIdentityKey,
+ entityMatchForms,
+ isValidEntityLabel,
normalizeEntityName,
+ sanitizeEntityLabel,
validateEntityCategory,
+ validateEntityLabel,
} from "../../../src/core/brain/entities/canonical.ts";
describe("normalizeEntityName", () => {
@@ -67,3 +74,134 @@ describe("validateEntityCategory", () => {
expect(() => validateEntityCategory("payment systems")).toThrow();
});
});
+
+describe("sanitizeEntityLabel", () => {
+ test("leaves clean labels byte-identical to a trim (backward compatible)", () => {
+ const clean = ["Ada", "Open Second Brain", "café", "Ада", "北京", "Node.js", "C++", "e.g"];
+ for (const label of clean) {
+ expect(sanitizeEntityLabel(label)).toBe(label);
+ // The intake pass must not shift the identity key of a clean label.
+ expect(entityIdentityKey("people", sanitizeEntityLabel(label))).toBe(
+ entityIdentityKey("people", label),
+ );
+ }
+ });
+
+ test("trims surrounding whitespace like the previous intake did", () => {
+ expect(sanitizeEntityLabel(" Ada ")).toBe("Ada");
+ });
+
+ test("strips Markdown emphasis wrappers", () => {
+ expect(sanitizeEntityLabel("**Foo**")).toBe("Foo");
+ expect(sanitizeEntityLabel("__Foo__")).toBe("Foo");
+ expect(sanitizeEntityLabel("*Foo*")).toBe("Foo");
+ expect(sanitizeEntityLabel("_Foo_")).toBe("Foo");
+ expect(sanitizeEntityLabel("`Foo`")).toBe("Foo");
+ expect(sanitizeEntityLabel("***Foo***")).toBe("Foo");
+ });
+
+ test("strips a leading Markdown heading marker", () => {
+ expect(sanitizeEntityLabel("# Heading")).toBe("Heading");
+ expect(sanitizeEntityLabel("### Deep Heading")).toBe("Deep Heading");
+ });
+
+ test("strips surrounding but not internal punctuation", () => {
+ expect(sanitizeEntityLabel("Foo.")).toBe("Foo");
+ expect(sanitizeEntityLabel("Foo:")).toBe("Foo");
+ expect(sanitizeEntityLabel("(baz)")).toBe("baz");
+ expect(sanitizeEntityLabel('"quoted"')).toBe("quoted");
+ expect(sanitizeEntityLabel("-Foo-")).toBe("Foo");
+ // Internal punctuation is preserved.
+ expect(sanitizeEntityLabel("Node.js")).toBe("Node.js");
+ expect(sanitizeEntityLabel("New York, NY")).toBe("New York, NY");
+ });
+
+ test("strips CJK brackets (language-agnostic punctuation classes)", () => {
+ expect(sanitizeEntityLabel("「名前」")).toBe("名前");
+ });
+
+ test("iterates nested decoration until stable", () => {
+ expect(sanitizeEntityLabel("**(Foo)**")).toBe("Foo");
+ expect(sanitizeEntityLabel("# **Heading.**")).toBe("Heading");
+ });
+
+ test("collapses pure-punctuation input to empty", () => {
+ expect(sanitizeEntityLabel("***")).toBe("");
+ expect(sanitizeEntityLabel("!!!")).toBe("");
+ expect(sanitizeEntityLabel("( )")).toBe("");
+ });
+});
+
+describe("validateEntityLabel", () => {
+ test("accepts letter/digit labels in any script", () => {
+ for (const label of ["Ada", "café", "Ада", "北京", "R2D2", "42"]) {
+ expect(validateEntityLabel(label)).toEqual({ valid: true });
+ }
+ });
+
+ test("rejects empty after strip", () => {
+ expect(validateEntityLabel("")).toEqual({ valid: false, reason: "empty" });
+ });
+
+ test("rejects labels with no letter or digit in any script", () => {
+ // A sanitized label can still be pure symbol (e.g. currency/math signs
+ // that are \p{S}, not \p{P}, so they survive stripping).
+ expect(validateEntityLabel("$$$")).toEqual({ valid: false, reason: "no-letter-or-digit" });
+ });
+
+ test("rejects labels over the length bound", () => {
+ const long = "a".repeat(ENTITY_LABEL_MAX_LENGTH + 1);
+ expect(validateEntityLabel(long)).toEqual({ valid: false, reason: "too-long" });
+ expect(validateEntityLabel("a".repeat(ENTITY_LABEL_MAX_LENGTH))).toEqual({ valid: true });
+ });
+
+ test("rejects a denylisted label compared post-normalization", () => {
+ const denylist = new Set([normalizeEntityName("Blocked Name")]);
+ expect(validateEntityLabel("blocked name", { denylist })).toEqual({
+ valid: false,
+ reason: "denylisted",
+ });
+ expect(validateEntityLabel("Allowed", { denylist })).toEqual({ valid: true });
+ });
+
+ test("isValidEntityLabel mirrors the validation verdict", () => {
+ expect(isValidEntityLabel("Ada")).toBe(true);
+ expect(isValidEntityLabel("!!!")).toBe(false);
+ });
+});
+
+describe("assertValidEntityLabel", () => {
+ test("returns the sanitized label on success", () => {
+ expect(assertValidEntityLabel("**Foo**")).toBe("Foo");
+ expect(assertValidEntityLabel("Ada")).toBe("Ada");
+ });
+
+ test("throws a typed InvalidEntityLabelError carrying the reason", () => {
+ try {
+ assertValidEntityLabel("***");
+ throw new Error("expected assertValidEntityLabel to throw");
+ } catch (err) {
+ expect(err).toBeInstanceOf(InvalidEntityLabelError);
+ expect((err as InvalidEntityLabelError).reason).toBe("empty");
+ }
+ });
+
+ test("throws on a denylisted label", () => {
+ const denylist = new Set([normalizeEntityName("nope")]);
+ expect(() => assertValidEntityLabel("Nope", { denylist })).toThrow(InvalidEntityLabelError);
+ });
+});
+
+describe("entityMatchForms", () => {
+ test("sanitizes and normalizes valid forms, dropping junk", () => {
+ expect(entityMatchForms(["**Google**", "Ада", "***", "Foo."])).toEqual([
+ "google",
+ "ада",
+ "foo",
+ ]);
+ });
+
+ test("clean forms normalize exactly as before (backward compatible)", () => {
+ expect(entityMatchForms(["Open Second Brain"])).toEqual(["open second brain"]);
+ });
+});
diff --git a/tests/core/brain/entities.label-hygiene.test.ts b/tests/core/brain/entities.label-hygiene.test.ts
new file mode 100644
index 00000000..3393474b
--- /dev/null
+++ b/tests/core/brain/entities.label-hygiene.test.ts
@@ -0,0 +1,185 @@
+/**
+ * A1 (t_657b365e): entity-label hygiene - denylist resolution, malformed
+ * node detection, and the snapshot-gated prune leaving no orphaned edges.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, 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 { writeFrontmatterAtomic } from "../../../src/core/vault.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { runDoctor } from "../../../src/core/brain/doctor.ts";
+import { __clearEntityIndexCache } from "../../../src/core/brain/entities/index-builder.ts";
+import {
+ ENTITY_LABEL_DENYLIST_ENV_KEY,
+ findMalformedEntityLabels,
+ pruneEntityLabels,
+ resolveEntityLabelDenylist,
+} from "../../../src/core/brain/entities/label-hygiene.ts";
+import { listSnapshots } from "../../../src/core/brain/snapshot.ts";
+
+let vault: string;
+let configHome: string;
+let originalDenylist: string | undefined;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+beforeEach(() => {
+ originalDenylist = process.env[ENTITY_LABEL_DENYLIST_ENV_KEY];
+ vault = mkdtempSync(join(tmpdir(), "o2b-label-hygiene-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-label-hygiene-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+ __clearEntityIndexCache();
+ delete process.env[ENTITY_LABEL_DENYLIST_ENV_KEY];
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ __clearEntityIndexCache();
+ // Restore any pre-existing env value so this suite does not contaminate
+ // other tests sharing the process.
+ if (originalDenylist === undefined) {
+ delete process.env[ENTITY_LABEL_DENYLIST_ENV_KEY];
+ } else {
+ process.env[ENTITY_LABEL_DENYLIST_ENV_KEY] = originalDenylist;
+ }
+});
+
+/** Write an entity node file directly, bypassing the creation quality gate. */
+function writeEntityNode(
+ category: string,
+ id: string,
+ name: string,
+ extra: Record<string, unknown> = {},
+): string {
+ const dir = join(brainDirs(vault).entities, category);
+ mkdirSync(dir, { recursive: true });
+ const path = join(dir, `${id}.md`);
+ writeFrontmatterAtomic(
+ path,
+ {
+ kind: "brain-entity",
+ entity_id: id,
+ category,
+ name,
+ status: "active",
+ created_at: "2026-07-18T00:00:00Z",
+ updated_at: "2026-07-18T00:00:00Z",
+ tags: ["brain", "brain/entity"],
+ ...extra,
+ },
+ `# ${name}`,
+ { overwrite: true },
+ );
+ __clearEntityIndexCache();
+ return path;
+}
+
+describe("resolveEntityLabelDenylist", () => {
+ test("is empty by default", () => {
+ expect(resolveEntityLabelDenylist().size).toBe(0);
+ });
+
+ test("reads the env twin as a comma-separated post-normalized set", () => {
+ process.env[ENTITY_LABEL_DENYLIST_ENV_KEY] = "Blocked Name, Other";
+ try {
+ const set = resolveEntityLabelDenylist();
+ expect(set.has("blocked name")).toBe(true);
+ expect(set.has("other")).toBe(true);
+ expect(set.has("Blocked Name")).toBe(false); // normalised, not raw
+ } finally {
+ delete process.env[ENTITY_LABEL_DENYLIST_ENV_KEY];
+ }
+ });
+});
+
+describe("findMalformedEntityLabels", () => {
+ test("returns only nodes whose labels fail the gate", () => {
+ writeEntityNode("people", "ent-people-ada", "Ada");
+ writeEntityNode("people", "ent-people-junk", "***");
+ const malformed = findMalformedEntityLabels(vault);
+ expect(malformed.map((m) => m.id)).toEqual(["ent-people-junk"]);
+ expect(malformed[0]!.reason).toBe("empty");
+ });
+
+ test("flags a denylisted label", () => {
+ writeEntityNode("people", "ent-people-ada", "Ada");
+ const denylist = new Set(["ada"]);
+ const malformed = findMalformedEntityLabels(vault, { denylist });
+ expect(malformed.map((m) => m.id)).toEqual(["ent-people-ada"]);
+ expect(malformed[0]!.reason).toBe("denylisted");
+ });
+
+ test("records inbound references from other nodes", () => {
+ writeEntityNode("people", "ent-people-junk", "***");
+ writeEntityNode("people", "ent-people-ada", "Ada", {
+ related: ["[[ent-people-junk]]"],
+ });
+ const malformed = findMalformedEntityLabels(vault);
+ expect(malformed[0]!.inboundReferences).toEqual(["ent-people-ada"]);
+ });
+});
+
+describe("pruneEntityLabels", () => {
+ test("dry-run lists candidates and mutates nothing (no snapshot)", () => {
+ const junkPath = writeEntityNode("people", "ent-people-junk", "***");
+ const result = pruneEntityLabels(vault, { confirm: false, now: NOW });
+ expect(result.confirmed).toBe(false);
+ expect(result.candidates.map((c) => c.id)).toEqual(["ent-people-junk"]);
+ expect(result.removed).toEqual([]);
+ expect(result.snapshotRunId).toBeNull();
+ expect(existsSync(junkPath)).toBe(true);
+ expect(listSnapshots(vault)).toHaveLength(0);
+ });
+
+ test("confirm removes the node and its edges behind a snapshot, doctor-clean", () => {
+ const junkPath = writeEntityNode("people", "ent-people-junk", "***");
+ writeEntityNode("people", "ent-people-ada", "Ada", {
+ related: ["[[ent-people-junk]]"],
+ });
+
+ const result = pruneEntityLabels(vault, { confirm: true, now: NOW });
+ expect(result.confirmed).toBe(true);
+ expect(result.removed).toEqual([junkPath]);
+ expect(result.edgesStripped).toBe(1);
+ expect(result.snapshotRunId).toMatch(/^entity-prune-/);
+ expect(result.snapshotPath).not.toBeNull();
+
+ // Node file gone, snapshot recovery point written.
+ expect(existsSync(junkPath)).toBe(false);
+ expect(listSnapshots(vault).length).toBeGreaterThan(0);
+
+ // No orphaned references remain: the inbound edge was stripped, so the
+ // doctor reports neither a broken relation nor a malformed-label lint.
+ const doctor = runDoctor(vault);
+ const codes = [...doctor.warnings, ...doctor.errors].map((i) => i.code);
+ expect(codes).not.toContain("broken-entity-relation");
+ expect(codes).not.toContain("entity-label-malformed");
+ });
+
+ test("confirm with no candidates is a no-op that takes no snapshot", () => {
+ writeEntityNode("people", "ent-people-ada", "Ada");
+ const result = pruneEntityLabels(vault, { confirm: true, now: NOW });
+ expect(result.confirmed).toBe(false);
+ expect(result.removed).toEqual([]);
+ expect(listSnapshots(vault)).toHaveLength(0);
+ });
+});
+
+describe("doctor entity-label-malformed lint", () => {
+ test("surfaces a malformed node as a warning prune candidate", () => {
+ writeEntityNode("people", "ent-people-junk", "***");
+ const doctor = runDoctor(vault);
+ const lint = doctor.warnings.find((i) => i.code === "entity-label-malformed");
+ expect(lint).toBeDefined();
+ expect(lint!.severity).toBe("warning");
+ expect(lint!.message).toContain("ent-people-junk");
+ });
+});
diff --git a/tests/core/brain/entities.registry.test.ts b/tests/core/brain/entities.registry.test.ts
index ab9a7dc7..ae8973c8 100644
--- a/tests/core/brain/entities.registry.test.ts
+++ b/tests/core/brain/entities.registry.test.ts
@@ -142,7 +142,9 @@ describe("upsertEntity", () => {
expect(listEntities(vault)).toHaveLength(2);
});
- test("rejects empty names", () => {
+ test("rejects empty names via the label quality gate", () => {
+ // A1: an empty (post-strip) name is now rejected by the typed label
+ // quality gate rather than the old bespoke "name must not be empty".
expect(() =>
upsertEntity(vault, {
category: "people",
@@ -150,7 +152,29 @@ describe("upsertEntity", () => {
agent: "claude-dev-agent",
now: NOW,
}),
- ).toThrow(/name/i);
+ ).toThrow(/invalid entity label/i);
+ });
+
+ test("strips Markdown/punctuation decoration from the stored name (A1)", () => {
+ const { entity } = upsertEntity(vault, {
+ category: "projects",
+ name: "**Mercury.**",
+ agent: "claude-dev-agent",
+ now: NOW,
+ });
+ expect(entity.name).toBe("Mercury");
+ expect(entity.id).toBe("ent-projects-mercury");
+ });
+
+ test("rejects a structurally-junk name with a typed error (A1)", () => {
+ expect(() =>
+ upsertEntity(vault, {
+ category: "people",
+ name: "***",
+ agent: "claude-dev-agent",
+ now: NOW,
+ }),
+ ).toThrow(/invalid entity label/i);
});
});
diff --git a/tests/core/brain/fact-extract.anchoring.test.ts b/tests/core/brain/fact-extract.anchoring.test.ts
new file mode 100644
index 00000000..db87f206
--- /dev/null
+++ b/tests/core/brain/fact-extract.anchoring.test.ts
@@ -0,0 +1,155 @@
+/**
+ * A1 (t_657b365e): fact-extract anchoring applies the label quality gate
+ * to stored entity labels. A junk-label node is skipped-with-log and the
+ * skip never breaks the enclosing capture (per-fact containment).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, 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 { writeFrontmatterAtomic } from "../../../src/core/vault.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { readLogDay } from "../../../src/core/brain/log-jsonl.ts";
+import { __clearEntityIndexCache } from "../../../src/core/brain/entities/index-builder.ts";
+import { routeExtractedFacts, type ExtractedFact } from "../../../src/core/brain/fact-extract.ts";
+import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
+
+let vault: string;
+let configHome: string;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-anchor-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-anchor-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+ __clearEntityIndexCache();
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ __clearEntityIndexCache();
+});
+
+function writeEntityNode(
+ category: string,
+ id: string,
+ name: string,
+ aliases: ReadonlyArray<string> = [],
+): void {
+ const dir = join(brainDirs(vault).entities, category);
+ mkdirSync(dir, { recursive: true });
+ writeFrontmatterAtomic(
+ join(dir, `${id}.md`),
+ {
+ kind: "brain-entity",
+ entity_id: id,
+ category,
+ name,
+ ...(aliases.length > 0 ? { aliases: [...aliases] } : {}),
+ status: "active",
+ created_at: "2026-07-18T00:00:00Z",
+ updated_at: "2026-07-18T00:00:00Z",
+ tags: ["brain", "brain/entity"],
+ },
+ `# ${name}`,
+ { overwrite: true },
+ );
+ __clearEntityIndexCache();
+}
+
+function inboxSignalBodies(): string[] {
+ const dir = brainDirs(vault).inbox;
+ return readdirSync(dir)
+ .filter((f) => f.startsWith("sig-") && f.endsWith(".md"))
+ .map((f) => readFileSync(join(dir, f), "utf8"));
+}
+
+describe("routeExtractedFacts anchoring with a junk-label node", () => {
+ test("skips the junk node, logs the skip, and still captures the fact", () => {
+ writeEntityNode("orgs", "ent-orgs-acme", "Acme");
+ writeEntityNode("orgs", "ent-orgs-junk", "***");
+
+ const facts: ExtractedFact[] = [{ family: "quantity", text: "acme shipped 5 units", line: 1 }];
+ const dedup = new Map<string, DedupIndexEntry>();
+ const result = routeExtractedFacts(vault, {
+ facts,
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-1",
+ dedup,
+ });
+
+ // The capture completed - the junk-label skip did not break it.
+ expect(result.created).toBe(1);
+
+ // The written signal anchors the valid entity but never the junk one.
+ const bodies = inboxSignalBodies();
+ const anchored = bodies.find((b) => b.includes("entities:"));
+ expect(anchored).toBeDefined();
+ expect(anchored!).toContain("ent-orgs-acme");
+ expect(anchored!).not.toContain("ent-orgs-junk");
+
+ // The skip is logged under the dedicated event kind.
+ const log = readLogDay(vault, "2026-07-18");
+ const skip = log.entries.find((e) => e.eventType === "entity-anchor-skip");
+ expect(skip).toBeDefined();
+ expect(skip!.body["entity"]).toBe("ent-orgs-junk");
+ expect(skip!.body["reason"]).toBe("empty");
+ });
+
+ test("anchors on a valid alias even when the name fails the gate, and logs the name skip", () => {
+ // The name is structurally junk but a valid alias survives the gate.
+ // The entity must NOT be silently excluded: it anchors via the alias,
+ // aligned with the atomic-facts anchoring path, while the name skip is
+ // still logged.
+ writeEntityNode("orgs", "ent-orgs-junkname", "***", ["Initech"]);
+
+ const dedup = new Map<string, DedupIndexEntry>();
+ const result = routeExtractedFacts(vault, {
+ facts: [{ family: "quantity", text: "initech shipped 7 units", line: 1 }],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-3",
+ dedup,
+ });
+ expect(result.created).toBe(1);
+
+ // Anchored via the valid alias form.
+ const anchored = inboxSignalBodies().find((b) => b.includes("entities:"));
+ expect(anchored).toBeDefined();
+ expect(anchored!).toContain("ent-orgs-junkname");
+
+ // The junk NAME skip is still logged.
+ const log = readLogDay(vault, "2026-07-18");
+ const skip = log.entries.find(
+ (e) => e.eventType === "entity-anchor-skip" && e.body["entity"] === "ent-orgs-junkname",
+ );
+ expect(skip).toBeDefined();
+ expect(skip!.body["reason"]).toBe("empty");
+ });
+
+ test("a decorated stored name still anchors after sanitisation", () => {
+ // A historical node whose name carries Markdown emphasis is still a
+ // valid label after stripping, so anchoring must resolve it.
+ writeEntityNode("orgs", "ent-orgs-globex", "**Globex**");
+ const dedup = new Map<string, DedupIndexEntry>();
+ routeExtractedFacts(vault, {
+ facts: [{ family: "quantity", text: "globex raised 10 units", line: 1 }],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-2",
+ dedup,
+ });
+ const anchored = inboxSignalBodies().find((b) => b.includes("entities:"));
+ expect(anchored).toBeDefined();
+ expect(anchored!).toContain("ent-orgs-globex");
+ });
+});
diff --git a/tests/core/brain/fact-extract.durability.test.ts b/tests/core/brain/fact-extract.durability.test.ts
new file mode 100644
index 00000000..6a583239
--- /dev/null
+++ b/tests/core/brain/fact-extract.durability.test.ts
@@ -0,0 +1,155 @@
+/**
+ * A2 (t_375e98fd): the durability gate inside `routeExtractedFacts`.
+ *
+ * The gate runs AFTER dedup and BEFORE the write (the fixed chain order:
+ * dedup -> durability -> staging -> write). A rejected fact is never silently
+ * dropped: it increments a counted, logged skip under the `durability-skip`
+ * event kind and is surfaced on the result via `durabilityRejected`. The
+ * operator `brain_feedback` path (a direct `writeSignal`) is NOT gated.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { readLogDay } from "../../../src/core/brain/log-jsonl.ts";
+import { writeSignal } from "../../../src/core/brain/signal.ts";
+import {
+ factDedupHash,
+ routeExtractedFacts,
+ type ExtractedFact,
+} from "../../../src/core/brain/fact-extract.ts";
+import { compileDurabilityDenylist } from "../../../src/core/brain/gates/durability.ts";
+import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
+
+let vault: string;
+let configHome: string;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-durability-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-durability-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 });
+});
+
+function inboxSignalNames(): string[] {
+ return readdirSync(brainDirs(vault).inbox).filter(
+ (f) => f.startsWith("sig-") && f.endsWith(".md"),
+ );
+}
+
+describe("routeExtractedFacts durability gate", () => {
+ test("a transient fact is rejected, counted, logged, and not written", () => {
+ const facts: ExtractedFact[] = [
+ { family: "url", text: "https://techmeat.dev", line: 1 }, // durable
+ { family: "quantity", text: "load 500ms render 200ms", line: 2 }, // transient
+ ];
+ const dedup = new Map<string, DedupIndexEntry>();
+ const result = routeExtractedFacts(vault, {
+ facts,
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-1",
+ dedup,
+ });
+
+ expect(result.created).toBe(1);
+ expect(result.deduped).toBe(0);
+ expect(result.durabilityRejected).toBe(1);
+
+ // Only the durable fact reached the inbox.
+ expect(inboxSignalNames().length).toBe(1);
+
+ // The rejected fact is logged under the dedicated event kind, never dropped.
+ const log = readLogDay(vault, "2026-07-18");
+ const skip = log.entries.find((e) => e.eventType === "durability-skip");
+ expect(skip).toBeDefined();
+ expect(skip!.body["family"]).toBe("quantity");
+ expect(skip!.body["reason"]).toBe("measurement-dominant");
+ expect(skip!.body["hash"]).toBe(
+ factDedupHash({ family: "quantity", text: "load 500ms render 200ms" }),
+ );
+ });
+
+ test("a deduped fact never reaches the gate (chain order dedup -> durability)", () => {
+ // Seed the dedup index with a TRANSIENT fact's hash. On route it must be
+ // counted as deduped, not durability-rejected, and produce no skip log.
+ const transient: ExtractedFact = { family: "quantity", text: "step 3/10", line: 1 };
+ const dedup = new Map<string, DedupIndexEntry>([
+ [factDedupHash(transient), { id: "sig-existing", path: "Brain/inbox/sig-existing.md" }],
+ ]);
+ const result = routeExtractedFacts(vault, {
+ facts: [transient],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-2",
+ dedup,
+ });
+
+ expect(result.deduped).toBe(1);
+ expect(result.durabilityRejected).toBe(0);
+ const log = readLogDay(vault, "2026-07-18");
+ expect(log.entries.some((e) => e.eventType === "durability-skip")).toBe(false);
+ });
+
+ test("an operator-supplied denylist regex extends the gate", () => {
+ const denylist = compileDurabilityDenylist("^scratch:");
+ const result = routeExtractedFacts(vault, {
+ facts: [{ family: "url", text: "scratch: https://throwaway.dev", line: 1 }],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-3",
+ dedup: new Map(),
+ durabilityDenylist: denylist,
+ });
+ expect(result.created).toBe(0);
+ expect(result.durabilityRejected).toBe(1);
+ const skip = readLogDay(vault, "2026-07-18").entries.find(
+ (e) => e.eventType === "durability-skip",
+ );
+ expect(skip!.body["reason"]).toBe("denylisted");
+ });
+
+ test("the operator writeSignal path is NOT gated by durability", () => {
+ // brain_feedback writes go straight through writeSignal (not
+ // routeExtractedFacts). A transient-looking principle must still land.
+ const res = writeSignal(vault, {
+ topic: "fact-check",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "load 500ms render 200ms", // would be rejected on the extracted path
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-check",
+ });
+ expect(res.id).toContain("sig-2026-07-18-fact-check");
+ expect(inboxSignalNames().length).toBe(1);
+ });
+
+ test("all-durable facts leave durabilityRejected at zero", () => {
+ const result = routeExtractedFacts(vault, {
+ facts: [
+ { family: "email", text: "[email protected]", line: 1 },
+ { family: "url", text: "https://techmeat.dev/blog", line: 2 },
+ ],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "session#turn-4",
+ dedup: new Map(),
+ });
+ expect(result.created).toBe(2);
+ expect(result.durabilityRejected).toBe(0);
+ });
+});
diff --git a/tests/core/brain/gates/durability.test.ts b/tests/core/brain/gates/durability.test.ts
new file mode 100644
index 00000000..321ca324
--- /dev/null
+++ b/tests/core/brain/gates/durability.test.ts
@@ -0,0 +1,247 @@
+/**
+ * A2 (t_375e98fd): deterministic durability gate. `classifyDurability` flags
+ * transient operational content through STRUCTURAL signals only - zero
+ * built-in natural-language word lists in any language. Each detector is
+ * tested with positive and negative cases; the non-Latin cases prove the
+ * classifier is language-agnostic (a plain sentence in any script that
+ * carries no structural signal is durable).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ classifyDurability,
+ compileDurabilityDenylist,
+ hasExitStatusShape,
+ hasMeasurementDominance,
+ hasProgressCounter,
+ hasRunIdShape,
+ hasTempPath,
+ type DurabilitySignal,
+} from "../../../../src/core/brain/gates/durability.ts";
+
+describe("classifyDurability - determinism (pure)", () => {
+ test("same input yields the same verdict across repeated calls", () => {
+ const samples = [
+ "https://techmeat.dev",
+ "/tmp/build-output.log",
+ "loaded in 500ms render 200ms",
+ "step 3/10 done",
+ "run-20260718-120000",
+ "process died with SIGKILL",
+ "Это важное правило для команды",
+ "重要な設計上の決定です",
+ ];
+ for (const s of samples) {
+ const first = classifyDurability(s);
+ for (let i = 0; i < 5; i++) {
+ expect(classifyDurability(s)).toEqual(first);
+ }
+ }
+ });
+});
+
+describe("temp-path detector", () => {
+ test("positive: filesystem temp paths", () => {
+ expect(hasTempPath("wrote /tmp/session.json")).toBe(true);
+ expect(hasTempPath("/var/tmp/cache")).toBe(true);
+ expect(hasTempPath("/var/folders/qx/abc/T/x")).toBe(true);
+ expect(hasTempPath("output saved to report.tmp")).toBe(true);
+ expect(hasTempPath("C:\\Users\\a\\AppData\\Local\\Temp\\x")).toBe(true);
+ expect(hasTempPath("cleared %TEMP%")).toBe(true);
+ expect(hasTempPath("in $TMPDIR")).toBe(true);
+ });
+
+ test("negative: durable text that merely mentions similar words", () => {
+ // No temp-path SHAPE, just a prose noun - must not fire (no word lists).
+ expect(hasTempPath("the temperature is stable")).toBe(false);
+ expect(hasTempPath("https://example.com/attempts")).toBe(false);
+ expect(hasTempPath("[email protected]")).toBe(false);
+ });
+});
+
+describe("progress-counter detector", () => {
+ test("positive: N/M ratios and NN% percentages", () => {
+ expect(hasProgressCounter("step 3/10")).toBe(true);
+ expect(hasProgressCounter("42/100 complete")).toBe(true);
+ expect(hasProgressCounter("done 87%")).toBe(true);
+ expect(hasProgressCounter("50%")).toBe(true);
+ });
+
+ test("negative: durable text without a counter shape", () => {
+ expect(hasProgressCounter("https://techmeat.dev/blog")).toBe(false);
+ expect(hasProgressCounter("paid 120 USD")).toBe(false);
+ expect(hasProgressCounter("[email protected]")).toBe(false);
+ });
+
+ test("negative: a percentage embedded in a factual sentence is not counter-dominant", () => {
+ // Regression: an incidental percentage in prose must NOT be classified as
+ // a transient progress counter and discarded.
+ expect(hasProgressCounter("Acme owns 50% of the venture")).toBe(false);
+ expect(hasProgressCounter("the survey found that 87% of respondents agreed")).toBe(false);
+ expect(hasProgressCounter("the display uses a 16/9 aspect ratio in the spec")).toBe(false);
+ expect(classifyDurability("Acme owns 50% of the venture").durable).toBe(true);
+ });
+
+ test("positive: counter-dominant status strings still flagged", () => {
+ expect(hasProgressCounter("step 3/10 done")).toBe(true);
+ expect(classifyDurability("step 3/10 done").durable).toBe(false);
+ });
+});
+
+describe("run-id / timestamp detector", () => {
+ test("positive: run-id and timestamp shapes", () => {
+ expect(hasRunIdShape("run-20260718-120000")).toBe(true);
+ expect(hasRunIdShape("job_1721304000")).toBe(true);
+ expect(hasRunIdShape("build-987654")).toBe(true);
+ expect(hasRunIdShape("started at 2026-07-18T12:00:00Z")).toBe(true);
+ expect(hasRunIdShape("epoch 1721304000")).toBe(true);
+ });
+
+ test("negative: durable text with short numbers only", () => {
+ expect(hasRunIdShape("version 3 of the plan")).toBe(false);
+ expect(hasRunIdShape("paid 120 USD")).toBe(false);
+ expect(hasRunIdShape("[email protected]")).toBe(false);
+ });
+});
+
+describe("measurement-dominant detector", () => {
+ test("positive: measurement tokens dominate the content", () => {
+ expect(hasMeasurementDominance("500ms")).toBe(true);
+ expect(hasMeasurementDominance("load 500ms render 200ms")).toBe(true);
+ expect(hasMeasurementDominance("12MB 3s")).toBe(true);
+ });
+
+ test("negative: measurement is a minority token in durable prose", () => {
+ expect(hasMeasurementDominance("it took 500ms to load the whole page")).toBe(false);
+ expect(hasMeasurementDominance("budget is 3.5 USD per call")).toBe(false);
+ expect(hasMeasurementDominance("[email protected]")).toBe(false);
+ });
+});
+
+describe("exit-status detector", () => {
+ test("positive: POSIX signal identifiers and the shell exit-status var", () => {
+ expect(hasExitStatusShape("process received SIGKILL")).toBe(true);
+ expect(hasExitStatusShape("terminated by SIGTERM")).toBe(true);
+ expect(hasExitStatusShape("check $? after the run")).toBe(true);
+ });
+
+ test("negative: durable prose without a status shape", () => {
+ expect(hasExitStatusShape("the signal is strong")).toBe(false);
+ expect(hasExitStatusShape("Signature verified")).toBe(false);
+ expect(hasExitStatusShape("[email protected]")).toBe(false);
+ });
+});
+
+describe("classifyDurability - verdict + reason naming", () => {
+ const cases: ReadonlyArray<readonly [string, DurabilitySignal]> = [
+ ["/tmp/x.json", "temp-path"],
+ ["step 3/10", "progress-counter"],
+ ["run-20260718-120000", "run-id"],
+ ["load 500ms render 200ms", "measurement-dominant"],
+ ["died with SIGKILL", "exit-status"],
+ ];
+ for (const [text, reason] of cases) {
+ test(`"${text}" is transient with reason ${reason}`, () => {
+ const v = classifyDurability(text);
+ expect(v.durable).toBe(false);
+ expect(v.reason).toBe(reason);
+ });
+ }
+
+ test("durable content returns durable:true, reason:null", () => {
+ for (const s of ["https://techmeat.dev", "[email protected]", "paid 120 USD"]) {
+ expect(classifyDurability(s)).toEqual({ durable: true, reason: null });
+ }
+ });
+});
+
+describe("language agnosticism (no built-in word lists)", () => {
+ test("plain non-Latin sentences carry no structural signal - durable", () => {
+ const durableNonLatin = [
+ "Это важное правило для нашей команды", // Russian
+ "重要な設計上の決定を記録する", // Japanese
+ "هذه قاعدة مهمة للفريق", // Arabic
+ "이것은 팀을 위한 중요한 규칙입니다", // Korean
+ "价格是一百二十美元", // Chinese prose (no digits)
+ ];
+ for (const s of durableNonLatin) {
+ expect(classifyDurability(s)).toEqual({ durable: true, reason: null });
+ }
+ });
+
+ test("structural signals fire regardless of surrounding script", () => {
+ // The SAME structural shape embedded in non-Latin prose is still caught -
+ // structure, not language, is what the gate reads.
+ expect(classifyDurability("ログは /tmp/run.log にあります").durable).toBe(false);
+ expect(classifyDurability("прогресс 3/10 готово").durable).toBe(false);
+ });
+});
+
+describe("operator denylist (config regexes extend the gate)", () => {
+ test("compileDurabilityDenylist parses a comma-separated regex list", () => {
+ const res = compileDurabilityDenylist("^draft:, ^wip-");
+ expect(res.length).toBe(2);
+ expect(res[0]!.test("draft: throwaway")).toBe(true);
+ expect(res[1]!.test("wip-experiment")).toBe(true);
+ });
+
+ test("compileDurabilityDenylist tolerates an invalid pattern (skips it)", () => {
+ // An unparseable operator regex must never crash capture; it is skipped
+ // like an invalid timezone. The valid sibling still compiles.
+ const res = compileDurabilityDenylist("(unclosed, ^ok-");
+ expect(res.length).toBe(1);
+ expect(res[0]!.test("ok-fine")).toBe(true);
+ });
+
+ test("compileDurabilityDenylist skips catastrophic-backtracking patterns", () => {
+ // A nested-unbounded-quantifier regex (ReDoS) runs on every fact; it must
+ // be dropped before compilation so a crafted input cannot stall capture.
+ // The safe sibling still compiles.
+ const res = compileDurabilityDenylist("(a+)+$, ^scratch:");
+ expect(res.length).toBe(1);
+ expect(res[0]!.test("scratch: throwaway")).toBe(true);
+ // Bounded and single-level quantifiers remain allowed.
+ expect(compileDurabilityDenylist("(abc)+").length).toBe(1);
+ expect(compileDurabilityDenylist("(a{2}){3}").length).toBe(1);
+ // Classifying a would-be-catastrophic input stays fast (no hang) because
+ // the dangerous pattern was never compiled.
+ const denylist = compileDurabilityDenylist("(a+)+$");
+ const start = Date.now();
+ expect(classifyDurability(`${"a".repeat(40)}!`, { denylist }).durable).toBe(true);
+ expect(Date.now() - start).toBeLessThan(1000);
+ });
+
+ test("compileDurabilityDenylist on empty/absent yields no regexes", () => {
+ expect(compileDurabilityDenylist(undefined)).toEqual([]);
+ expect(compileDurabilityDenylist("")).toEqual([]);
+ expect(compileDurabilityDenylist(" , ")).toEqual([]);
+ });
+
+ test("a denylist match flags otherwise-durable content as denylisted", () => {
+ const denylist = compileDurabilityDenylist("^scratch:");
+ const v = classifyDurability("scratch: nothing to keep", { denylist });
+ expect(v.durable).toBe(false);
+ expect(v.reason).toBe("denylisted");
+ });
+
+ test("built-in structural signal wins over the denylist reason (table order)", () => {
+ // A temp path AND a denylist match: the built-in structural reason is
+ // reported (detectors run before the denylist), keeping reasons stable.
+ const denylist = compileDurabilityDenylist("keep");
+ const v = classifyDurability("/tmp/keep.json", { denylist });
+ expect(v.durable).toBe(false);
+ expect(v.reason).toBe("temp-path");
+ });
+
+ test("a global-flag-shaped operator regex stays deterministic across calls", () => {
+ // compileDurabilityDenylist must not carry statefulness into classify.
+ const denylist = compileDurabilityDenylist("scratch");
+ const text = "scratch pad";
+ const first = classifyDurability(text, { denylist });
+ for (let i = 0; i < 4; i++) {
+ expect(classifyDurability(text, { denylist })).toEqual(first);
+ }
+ });
+});
diff --git a/tests/core/brain/health/advise-on-incoming.test.ts b/tests/core/brain/health/advise-on-incoming.test.ts
new file mode 100644
index 00000000..80f1c262
--- /dev/null
+++ b/tests/core/brain/health/advise-on-incoming.test.ts
@@ -0,0 +1,118 @@
+/**
+ * A4 (t_f79b4fe0): write-time conflict advisory - pure helper.
+ *
+ * `adviseOnIncoming` compares an incoming feedback principle against
+ * already-confirmed same-scope preferences using the shared similarity
+ * kernel (`tokenise` + `jaccard`) and the health-pass default threshold.
+ * It is advisory only: it surfaces conflicting preference ids and their
+ * similarity, it never blocks a write. The bucketing rules mirror
+ * `detectContradictions` - only same-scope confirmed preferences count,
+ * and an unscoped incoming signal compares against the unscoped bucket.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { BRAIN_PREFERENCE_STATUS } from "../../../../src/core/brain/types.ts";
+import {
+ adviseOnIncoming,
+ type PreferenceForContradiction,
+} from "../../../../src/core/brain/health/contradiction.ts";
+
+function pref(
+ over: Partial<PreferenceForContradiction> & Pick<PreferenceForContradiction, "id" | "principle">,
+): PreferenceForContradiction {
+ return {
+ scope: "coding",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ evidenced_by: [],
+ ...over,
+ };
+}
+
+describe("adviseOnIncoming", () => {
+ test("flags a same-scope high-overlap confirmed preference", () => {
+ const advisory = adviseOnIncoming("always indent source with tabs not spaces", "coding", [
+ pref({ id: "pref-tabs", principle: "always indent source with tabs not spaces" }),
+ pref({ id: "pref-unrelated", principle: "write commit messages in imperative voice" }),
+ ]);
+ expect(advisory).not.toBeNull();
+ expect(advisory!.scope).toBe("coding");
+ expect(advisory!.conflicts.length).toBe(1);
+ expect(advisory!.conflicts[0]!.prefId).toBe("pref-tabs");
+ expect(advisory!.conflicts[0]!.jaccard).toBeGreaterThanOrEqual(0.5);
+ });
+
+ test("returns null for a non-conflicting (low-overlap) incoming principle", () => {
+ const advisory = adviseOnIncoming("prefer semantic HTML elements over generic divs", "coding", [
+ pref({ id: "pref-tabs", principle: "always indent source with tabs not spaces" }),
+ ]);
+ expect(advisory).toBeNull();
+ });
+
+ test("does not fire for a near-duplicate in a DIFFERENT scope", () => {
+ const advisory = adviseOnIncoming("always indent source with tabs not spaces", "writing", [
+ pref({
+ id: "pref-tabs",
+ scope: "coding",
+ principle: "always indent source with tabs not spaces",
+ }),
+ ]);
+ expect(advisory).toBeNull();
+ });
+
+ test("unscoped incoming compares against the unscoped bucket only", () => {
+ const advisory = adviseOnIncoming("always indent source with tabs not spaces", undefined, [
+ pref({
+ id: "pref-unscoped",
+ scope: undefined,
+ principle: "always indent source with tabs not spaces",
+ }),
+ pref({
+ id: "pref-scoped",
+ scope: "coding",
+ principle: "always indent source with tabs not spaces",
+ }),
+ ]);
+ expect(advisory).not.toBeNull();
+ expect(advisory!.scope).toBeNull();
+ expect(advisory!.conflicts.map((c) => c.prefId)).toEqual(["pref-unscoped"]);
+ });
+
+ test("ignores non-confirmed preferences", () => {
+ const advisory = adviseOnIncoming("always indent source with tabs not spaces", "coding", [
+ pref({
+ id: "pref-unconfirmed",
+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,
+ principle: "always indent source with tabs not spaces",
+ }),
+ ]);
+ expect(advisory).toBeNull();
+ });
+
+ test("sorts multiple conflicts by descending similarity then id", () => {
+ const advisory = adviseOnIncoming(
+ "always indent source code with tabs not spaces here",
+ "coding",
+ [
+ pref({
+ id: "pref-z",
+ principle: "always indent source code with tabs not spaces here",
+ }),
+ pref({
+ id: "pref-a",
+ principle: "always indent source code with tabs not spaces here",
+ }),
+ pref({ id: "pref-loose", principle: "always indent source code with tabs everywhere" }),
+ ],
+ );
+ expect(advisory).not.toBeNull();
+ // pref-a and pref-z tie on similarity (identical principles) and must
+ // break ties lexicographically by id; pref-loose is a weaker match.
+ expect(advisory!.conflicts.map((conflict) => conflict.prefId)).toEqual([
+ "pref-a",
+ "pref-z",
+ "pref-loose",
+ ]);
+ expect(advisory!.conflicts[0]!.jaccard).toBeGreaterThanOrEqual(advisory!.conflicts[2]!.jaccard);
+ });
+});
diff --git a/tests/core/brain/health/remediation.test.ts b/tests/core/brain/health/remediation.test.ts
index 50d40555..4c833884 100644
--- a/tests/core/brain/health/remediation.test.ts
+++ b/tests/core/brain/health/remediation.test.ts
@@ -9,7 +9,7 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -18,6 +18,7 @@ import { brainDirs } from "../../../../src/core/brain/paths.ts";
import { parsePreference, writePreference } from "../../../../src/core/brain/preference.ts";
import {
applyRemediation,
+ collectWidePermissions,
planRemediation,
} from "../../../../src/core/brain/health/remediation.ts";
import { BRAIN_PREFERENCE_STATUS } from "../../../../src/core/brain/types.ts";
@@ -128,3 +129,113 @@ describe("applyRemediation", () => {
expect(outcome.skipped.map((s) => s.target)).toContain("b-drift");
});
});
+
+describe("harden-permissions (D2)", () => {
+ // POSIX modes are meaningless on Windows; the migration is skipped
+ // there, so its assertions only run on POSIX hosts.
+ const posix = process.platform !== "win32";
+
+ test("collects Brain/ files wider than 0o600 and dirs wider than 0o700", () => {
+ if (!posix) return;
+ const dirs = brainDirs(vault);
+ const wideFile = join(dirs.preferences, "wide.md");
+ writeFileSync(wideFile, "x", "utf8");
+ chmodSync(wideFile, 0o644);
+ const tightFile = join(dirs.preferences, "tight.md");
+ writeFileSync(tightFile, "y", "utf8");
+ chmodSync(tightFile, 0o600);
+ chmodSync(dirs.preferences, 0o755);
+
+ const findings = collectWidePermissions(vault, { platform: "linux" });
+ const paths = findings.map((f) => f.path);
+ expect(paths).toContain("Brain/preferences/wide.md");
+ expect(paths).toContain("Brain/preferences");
+ // An already-tight file produces no finding (idempotence precondition).
+ expect(paths).not.toContain("Brain/preferences/tight.md");
+ const wide = findings.find((f) => f.path === "Brain/preferences/wide.md")!;
+ expect(wide.isDir).toBe(false);
+ const dirFinding = findings.find((f) => f.path === "Brain/preferences")!;
+ expect(dirFinding.isDir).toBe(true);
+ });
+
+ test("plans wide permissions as auto-safe steps and apply chmods them", () => {
+ if (!posix) return;
+ const dirs = brainDirs(vault);
+ const wideFile = join(dirs.preferences, "wide.md");
+ writeFileSync(wideFile, "x", "utf8");
+ chmodSync(wideFile, 0o646);
+
+ const plan = planRemediation(
+ {
+ ...allFindings,
+ driftedSlugs: [],
+ widePermissions: collectWidePermissions(vault, { platform: "linux" }),
+ },
+ { stepCap: 10 },
+ );
+ const permStep = plan.steps.find((s) => s.action === "harden-permissions");
+ expect(permStep).toBeDefined();
+ expect(permStep!.classification).toBe("auto-safe");
+
+ const outcome = applyRemediation(vault, plan, { dryRun: false });
+ expect(outcome.applied.some((s) => s.action === "harden-permissions")).toBe(true);
+ expect(statSync(wideFile).mode & 0o777).toBe(0o600);
+ });
+
+ test("dry-run lists the chmod without touching the file", () => {
+ if (!posix) return;
+ const dirs = brainDirs(vault);
+ const wideFile = join(dirs.preferences, "wide.md");
+ writeFileSync(wideFile, "x", "utf8");
+ chmodSync(wideFile, 0o644);
+
+ const plan = planRemediation(
+ {
+ driftedSlugs: [],
+ contradictions: [],
+ staleClaims: [],
+ conceptGaps: [],
+ widePermissions: collectWidePermissions(vault, { platform: "linux" }),
+ },
+ { stepCap: 10 },
+ );
+ const outcome = applyRemediation(vault, plan, { dryRun: true });
+ expect(outcome.applied.some((s) => s.action === "harden-permissions")).toBe(true);
+ // File is untouched under dry-run.
+ expect(statSync(wideFile).mode & 0o777).toBe(0o644);
+ });
+
+ test("re-running after a chmod is idempotent (no new findings)", () => {
+ if (!posix) return;
+ const dirs = brainDirs(vault);
+ const wideFile = join(dirs.preferences, "wide.md");
+ writeFileSync(wideFile, "x", "utf8");
+ chmodSync(wideFile, 0o644);
+
+ const plan = planRemediation(
+ {
+ driftedSlugs: [],
+ contradictions: [],
+ staleClaims: [],
+ conceptGaps: [],
+ widePermissions: collectWidePermissions(vault, { platform: "linux" }),
+ },
+ { stepCap: 10 },
+ );
+ applyRemediation(vault, plan, { dryRun: false });
+ // The second collection sees a hardened tree.
+ const second = collectWidePermissions(vault, { platform: "linux" });
+ expect(second.some((f) => f.path === "Brain/preferences/wide.md")).toBe(false);
+ });
+
+ test("windows is skipped cleanly with an explicit logged reason", () => {
+ const logged: string[] = [];
+ const findings = collectWidePermissions(vault, {
+ platform: "win32",
+ log: (m) => logged.push(m),
+ });
+ expect(findings).toEqual([]);
+ expect(logged.length).toBe(1);
+ expect(logged[0]).toMatch(/win32/i);
+ });
+});
diff --git a/tests/core/brain/pending.test.ts b/tests/core/brain/pending.test.ts
new file mode 100644
index 00000000..b9370ea2
--- /dev/null
+++ b/tests/core/brain/pending.test.ts
@@ -0,0 +1,244 @@
+/**
+ * A3 (t_e540b093): opt-in write-approval pending queue.
+ *
+ * With write_approval enabled, extracted signals are STAGED into
+ * Brain/pending/ with byte-identical frontmatter (default off preserves the
+ * direct-to-inbox path byte-for-byte). apply moves a staged file into
+ * Brain/inbox/ unchanged (anchors + dedup hash preserved); reject moves it to
+ * Brain/retired/ with retire-shaped frontmatter. Applying or rejecting a
+ * missing / already-processed id is a typed error, never a silent no-op.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { parseFrontmatter } from "../../../src/core/vault.ts";
+import { routeExtractedFacts, type ExtractedFact } from "../../../src/core/brain/fact-extract.ts";
+import {
+ applyPending,
+ listPending,
+ PendingSignalNotFoundError,
+ rejectPending,
+ stagePendingSignal,
+} from "../../../src/core/brain/pending.ts";
+import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
+
+let vault: string;
+let configHome: string;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+function makeVault(): string {
+ const v = mkdtempSync(join(tmpdir(), "o2b-pending-vault-"));
+ const cfg = mkdtempSync(join(tmpdir(), "o2b-pending-cfg-"));
+ const configPath = join(cfg, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${v}\n`);
+ bootstrapBrain(v, { configPath });
+ toCleanup.push(v, cfg);
+ return v;
+}
+
+const toCleanup: string[] = [];
+
+beforeEach(() => {
+ vault = makeVault();
+ configHome = "";
+});
+
+afterEach(() => {
+ for (const p of toCleanup.splice(0)) rmSync(p, { recursive: true, force: true });
+ void configHome;
+});
+
+function names(dir: string): string[] {
+ if (!existsSync(dir)) return [];
+ return readdirSync(dir)
+ .filter((f) => f.startsWith("sig-") && f.endsWith(".md"))
+ .toSorted();
+}
+
+const URL_FACT: ExtractedFact = { family: "url", text: "https://techmeat.dev", line: 1 };
+
+describe("routeExtractedFacts staging decision", () => {
+ test("write_approval disabled writes to inbox (no pending dir touched)", () => {
+ const res = routeExtractedFacts(vault, {
+ facts: [URL_FACT],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "s#1",
+ dedup: new Map<string, DedupIndexEntry>(),
+ writeApprovalEnabled: false,
+ });
+ expect(res.created).toBe(1);
+ expect(names(brainDirs(vault).inbox).length).toBe(1);
+ expect(names(brainDirs(vault).pending).length).toBe(0);
+ });
+
+ test("write_approval enabled stages to pending, inbox stays empty", () => {
+ const res = routeExtractedFacts(vault, {
+ facts: [URL_FACT],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "s#1",
+ dedup: new Map<string, DedupIndexEntry>(),
+ writeApprovalEnabled: true,
+ });
+ expect(res.created).toBe(1);
+ expect(names(brainDirs(vault).pending).length).toBe(1);
+ expect(names(brainDirs(vault).inbox).length).toBe(0);
+ });
+
+ test("staged pending doc is byte-for-byte identical to the inbox doc", () => {
+ // Same input routed to two fresh vaults: one to inbox (disabled), one to
+ // pending (enabled). The documents must be identical byte-for-byte.
+ const inboxVault = makeVault();
+ routeExtractedFacts(inboxVault, {
+ facts: [URL_FACT],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "s#1",
+ dedup: new Map(),
+ writeApprovalEnabled: false,
+ });
+ routeExtractedFacts(vault, {
+ facts: [URL_FACT],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "s#1",
+ dedup: new Map(),
+ writeApprovalEnabled: true,
+ });
+ const inboxName = names(brainDirs(inboxVault).inbox)[0]!;
+ const pendingName = names(brainDirs(vault).pending)[0]!;
+ expect(pendingName).toBe(inboxName);
+ const inboxDoc = readFileSync(join(brainDirs(inboxVault).inbox, inboxName), "utf8");
+ const pendingDoc = readFileSync(join(brainDirs(vault).pending, pendingName), "utf8");
+ expect(pendingDoc).toBe(inboxDoc);
+ });
+});
+
+describe("stagePendingSignal", () => {
+ test("writes the identical frontmatter document into Brain/pending/", () => {
+ const res = stagePendingSignal(vault, {
+ topic: "fact-url",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "https://techmeat.dev",
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-url",
+ source_type: "extracted",
+ dedup_hash: "abc123",
+ });
+ expect(res.id).toBe("sig-2026-07-18-fact-url");
+ expect(existsSync(res.path)).toBe(true);
+ expect(res.path.startsWith(brainDirs(vault).pending)).toBe(true);
+ });
+});
+
+describe("listPending", () => {
+ test("returns the staged signals with their coordinates", () => {
+ stagePendingSignal(vault, {
+ topic: "fact-url",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "https://techmeat.dev",
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-url",
+ source_type: "extracted",
+ dedup_hash: "abc123",
+ });
+ const items = listPending(vault);
+ expect(items.length).toBe(1);
+ expect(items[0]!.id).toBe("sig-2026-07-18-fact-url");
+ expect(items[0]!.signal.principle).toBe("https://techmeat.dev");
+ });
+
+ test("empty (or absent) pending dir lists nothing", () => {
+ expect(listPending(vault)).toEqual([]);
+ });
+});
+
+describe("applyPending", () => {
+ test("moves a staged signal into inbox unchanged (anchors + dedup hash)", () => {
+ // Stage a signal carrying an entity anchor body + dedup hash.
+ const staged = stagePendingSignal(vault, {
+ topic: "fact-url",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "https://techmeat.dev",
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-url",
+ source_type: "extracted",
+ dedup_hash: "hash-xyz",
+ raw: "entities: ent-projects-techmeat",
+ });
+ const before = readFileSync(staged.path, "utf8");
+
+ const applied = applyPending(vault, staged.id);
+ expect(applied.id).toBe(staged.id);
+ expect(applied.path.startsWith(brainDirs(vault).inbox)).toBe(true);
+
+ // Pending file gone, inbox file present, bytes preserved verbatim.
+ expect(existsSync(staged.path)).toBe(false);
+ const after = readFileSync(applied.path, "utf8");
+ expect(after).toBe(before);
+ expect(after).toContain("dedup_hash: hash-xyz");
+ expect(after).toContain("entities: ent-projects-techmeat");
+ });
+
+ test("applying a missing id is a typed error, not a no-op", () => {
+ expect(() => applyPending(vault, "sig-2026-07-18-nope")).toThrow(PendingSignalNotFoundError);
+ });
+
+ test("applying twice is a typed error the second time", () => {
+ const staged = stagePendingSignal(vault, {
+ topic: "fact-url",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "https://techmeat.dev",
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-url",
+ });
+ applyPending(vault, staged.id);
+ expect(() => applyPending(vault, staged.id)).toThrow(PendingSignalNotFoundError);
+ });
+});
+
+describe("rejectPending", () => {
+ test("moves a staged signal to retired with retire-shaped frontmatter", () => {
+ const staged = stagePendingSignal(vault, {
+ topic: "fact-url",
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: "https://techmeat.dev",
+ created_at: "2026-07-18T12:00:00Z",
+ date: "2026-07-18",
+ slug: "fact-url",
+ });
+ const rejected = rejectPending(vault, staged.id, "not useful", { now: NOW });
+ expect(existsSync(staged.path)).toBe(false);
+ expect(rejected.path.startsWith(brainDirs(vault).retired)).toBe(true);
+
+ const [meta] = parseFrontmatter(rejected.path);
+ expect(meta["_status"]).toBe("retired");
+ expect(meta["retired_at"]).toBe(NOW.toISOString());
+ expect(meta["retired_reason"]).toBe("not useful");
+ // The original signal content is preserved for the audit trail.
+ expect(meta["principle"]).toBe("https://techmeat.dev");
+ });
+
+ test("rejecting a missing id is a typed error", () => {
+ expect(() => rejectPending(vault, "sig-2026-07-18-nope", "x")).toThrow(
+ PendingSignalNotFoundError,
+ );
+ });
+});
diff --git a/tests/core/brain/signal-retire.test.ts b/tests/core/brain/signal-retire.test.ts
new file mode 100644
index 00000000..63319150
--- /dev/null
+++ b/tests/core/brain/signal-retire.test.ts
@@ -0,0 +1,152 @@
+/**
+ * A5 (t_66c12a67): fact signal retire lifecycle.
+ *
+ * `retireSignal` moves a `Brain/inbox/sig-*.md` file into `Brain/retired/`,
+ * rewrites its frontmatter with the retire metadata (mirroring the
+ * preference retire conventions and A3's rejectPending), appends an audit
+ * log event, and refuses source ids outside the inbox. Because the dream
+ * pass consumes `Brain/inbox/` only, the directory move IS the exclusion
+ * mechanism; the retired signal stays readable in `Brain/retired/`.
+ * Retiring a missing / already-retired / non-signal id is a typed error.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { parseFrontmatter } from "../../../src/core/vault.ts";
+import { parseSignal, writeSignal } from "../../../src/core/brain/signal.ts";
+import { queryByTopic, readAllLogEntries } from "../../../src/core/brain/query.ts";
+import { BRAIN_LOG_EVENT_KIND } from "../../../src/core/brain/types.ts";
+import {
+ InvalidSignalIdError,
+ retireSignal,
+ SignalAlreadyRetiredError,
+ SignalNotFoundError,
+} from "../../../src/core/brain/signal-retire.ts";
+
+let tmp: string;
+let vault: string;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+function seedSignal(slug: string, topic = slug): string {
+ const res = writeSignal(vault, {
+ topic,
+ signal: "positive",
+ agent: "claude-dev-agent",
+ principle: `https://${slug}.dev`,
+ created_at: NOW.toISOString(),
+ date: "2026-07-18",
+ slug,
+ source_type: "extracted",
+ dedup_hash: `hash-${slug}`,
+ });
+ return res.id;
+}
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-signal-retire-"));
+ vault = join(tmp, "vault");
+ const configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("retireSignal", () => {
+ test("moves the signal to retired/ and rewrites the frontmatter", () => {
+ const id = seedSignal("fact-url");
+ const res = retireSignal(vault, id, {
+ reason: "superseded by a fresher capture",
+ superseded_by: "sig-2026-07-19-fact-url",
+ agent: "claude-dev-agent",
+ now: NOW,
+ });
+
+ // Moved out of inbox, into retired.
+ expect(existsSync(join(brainDirs(vault).inbox, `${id}.md`))).toBe(false);
+ expect(res.path.startsWith(brainDirs(vault).retired)).toBe(true);
+ expect(existsSync(res.path)).toBe(true);
+
+ const [meta] = parseFrontmatter(res.path);
+ // Kind stays brain-signal (consistent with rejectPending).
+ expect(meta["kind"]).toBe("brain-signal");
+ expect(meta["_status"]).toBe("retired");
+ expect(meta["retired_at"]).toBe(NOW.toISOString());
+ expect(meta["retired_reason"]).toBe("superseded by a fresher capture");
+ expect(meta["superseded_by"]).toBe("sig-2026-07-19-fact-url");
+ expect(meta["retired_by"]).toBe("claude-dev-agent");
+ // Original signal fields preserved for the audit trail.
+ expect(meta["principle"]).toBe("https://fact-url.dev");
+ // Tag swapped brain/signal -> brain/retired.
+ expect(meta["tags"]).toContain("brain/retired");
+ expect(meta["tags"]).not.toContain("brain/signal");
+ // Old-id alias present.
+ expect(meta["aliases"]).toContain(id);
+ });
+
+ test("the retired signal is excluded from dream intake but stays readable", () => {
+ const id = seedSignal("fact-url", "fact-url-topic");
+ // Before retirement the dream-intake surface (inbox + processed) sees it.
+ expect(queryByTopic(vault, "fact-url-topic").signals.map((s) => s.id)).toContain(id);
+
+ const res = retireSignal(vault, id, { reason: "no longer relevant", now: NOW });
+
+ // The dream signal-collection surface no longer sees it.
+ expect(queryByTopic(vault, "fact-url-topic").signals.map((s) => s.id)).not.toContain(id);
+ // But it remains readable in the retired directory.
+ const reread = parseSignal(res.path);
+ expect(reread.id).toBe(id);
+ expect(reread.principle).toBe("https://fact-url.dev");
+ });
+
+ test("appends a signal-retire audit log event", () => {
+ const id = seedSignal("fact-url");
+ retireSignal(vault, id, { reason: "duplicate", agent: "claude-dev-agent", now: NOW });
+ const events = readAllLogEntries(vault).filter(
+ (e) => e.eventType === BRAIN_LOG_EVENT_KIND.signalRetire,
+ );
+ expect(events.length).toBe(1);
+ expect(events[0]!.body["signal"]).toBe(`[[${id}]]`);
+ expect(events[0]!.body["reason"]).toBe("duplicate");
+ });
+
+ test("missing id is a typed error", () => {
+ expect(() => retireSignal(vault, "sig-2026-07-18-absent", { reason: "x", now: NOW })).toThrow(
+ SignalNotFoundError,
+ );
+ });
+
+ test("already-retired id (present in retired/) is a typed error", () => {
+ const id = seedSignal("fact-url");
+ retireSignal(vault, id, { reason: "first", now: NOW });
+ expect(() => retireSignal(vault, id, { reason: "again", now: NOW })).toThrow(
+ SignalAlreadyRetiredError,
+ );
+ });
+
+ test("a ret-* id is treated as already retired", () => {
+ expect(() => retireSignal(vault, "ret-some-pref", { reason: "x", now: NOW })).toThrow(
+ SignalAlreadyRetiredError,
+ );
+ });
+
+ test("a non-signal id is a typed error", () => {
+ expect(() => retireSignal(vault, "pref-some-rule", { reason: "x", now: NOW })).toThrow(
+ InvalidSignalIdError,
+ );
+ });
+
+ test("an id with path traversal is refused (containment)", () => {
+ expect(() => retireSignal(vault, "../../etc/passwd", { reason: "x", now: NOW })).toThrow(
+ InvalidSignalIdError,
+ );
+ });
+});
diff --git a/tests/core/brain/snapshot-gate.test.ts b/tests/core/brain/snapshot-gate.test.ts
new file mode 100644
index 00000000..cc5fbe51
--- /dev/null
+++ b/tests/core/brain/snapshot-gate.test.ts
@@ -0,0 +1,154 @@
+/**
+ * D1 (t_7965b04b): snapshot-before-destructive-write gate.
+ *
+ * `withDestructiveSnapshot(vault, label, op)` is the thin wrapper that
+ * guarantees no destructive brain mutation runs without a recovery
+ * point on disk first. The contract:
+ *
+ * - it mints a valid, unique run id of the shape `<label>-<stamp>`;
+ * - it calls `createSnapshot` BEFORE `op`, so a snapshot failure
+ * aborts the operation (the destructive work never runs);
+ * - if `op` throws, the error propagates but the snapshot stays put
+ * (that IS the recovery point);
+ * - after a successful `op` it prunes to the configured retention.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { withDestructiveSnapshot } from "../../../src/core/brain/snapshot-gate.ts";
+import { listSnapshots } from "../../../src/core/brain/snapshot.ts";
+import { brainDirs, validateRunId } from "../../../src/core/brain/paths.ts";
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+let configPath: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-snap-gate-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-snap-gate-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+
+ const dirs = brainDirs(vault);
+ writeFileSync(
+ join(dirs.inbox, "sig-2026-05-14-foo.md"),
+ "---\nkind: brain-signal\n---\n\n## Raw\n\nseed\n",
+ );
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("withDestructiveSnapshot", () => {
+ test("mints a valid run id and snapshots before running op", () => {
+ let archiveCountWhenOpRan = -1;
+ const out = withDestructiveSnapshot(
+ vault,
+ "delete-by-source",
+ () => {
+ // The snapshot archive must already exist by the time op runs.
+ archiveCountWhenOpRan = listSnapshots(vault).length;
+ return "result-value";
+ },
+ { now: new Date("2026-06-01T00:00:00Z") },
+ );
+ expect(out.result).toBe("result-value");
+ expect(out.snapshot.runId).toMatch(/^delete-by-source-/);
+ // The minted id is a valid filesystem-safe run id.
+ expect(() => validateRunId(out.snapshot.runId)).not.toThrow();
+ expect(existsSync(out.snapshot.path)).toBe(true);
+ expect(archiveCountWhenOpRan).toBe(1);
+ });
+
+ test("op runs after the snapshot exists (order proven)", () => {
+ let order: string[] = [];
+ const before = listSnapshots(vault).length;
+ withDestructiveSnapshot(vault, "prune-entities", () => {
+ order.push(`snapshots=${listSnapshots(vault).length}`);
+ });
+ expect(order).toEqual([`snapshots=${before + 1}`]);
+ });
+
+ test("aborts the operation when the snapshot cannot be created", () => {
+ // Force createSnapshot to fail by making `tar` unfindable: point PATH
+ // at an empty dir so tooling detection reports tar missing.
+ const emptyDir = mkdtempSync(join(tmpdir(), "o2b-empty-path-"));
+ const savedPath = process.env["PATH"];
+ process.env["PATH"] = emptyDir;
+ let opRan = false;
+ try {
+ expect(() =>
+ withDestructiveSnapshot(vault, "delete-by-source", () => {
+ opRan = true;
+ }),
+ ).toThrow();
+ expect(opRan).toBe(false);
+ } finally {
+ process.env["PATH"] = savedPath;
+ rmSync(emptyDir, { recursive: true, force: true });
+ }
+ });
+
+ test("op error propagates but the snapshot is retained as recovery point", () => {
+ const before = listSnapshots(vault).length;
+ expect(() =>
+ withDestructiveSnapshot(vault, "delete-by-source", () => {
+ throw new Error("op blew up");
+ }),
+ ).toThrow("op blew up");
+ // The snapshot survives - it is the recovery point.
+ expect(listSnapshots(vault).length).toBe(before + 1);
+ });
+
+ test("prunes to the configured retention after a successful op", () => {
+ // Retention default is 10; write config with retention_count: 2.
+ const brainYaml = join(brainDirs(vault).brain, "_brain.yaml");
+ atomicWriteFileSync(brainYaml, "schema_version: 1\nsnapshots:\n retention_count: 2\n");
+
+ // Create three snapshots through the gate; only the two newest survive.
+ for (let i = 0; i < 3; i++) {
+ withDestructiveSnapshot(vault, "delete-by-source", () => undefined, {
+ now: new Date(`2026-06-0${i + 1}T00:00:00Z`),
+ });
+ }
+ expect(listSnapshots(vault).length).toBe(2);
+ });
+
+ test("mints unique run ids when the base id already exists", () => {
+ const now = new Date("2026-06-01T00:00:00Z");
+ const a = withDestructiveSnapshot(vault, "delete-by-source", () => undefined, { now });
+ const b = withDestructiveSnapshot(vault, "delete-by-source", () => undefined, { now });
+ expect(a.snapshot.runId).not.toBe(b.snapshot.runId);
+ expect(b.snapshot.runId).toBe(`${a.snapshot.runId}-2`);
+ });
+
+ test("the minted snapshot archive contains the seeded Brain content", () => {
+ const out = withDestructiveSnapshot(vault, "delete-by-source", () => undefined);
+ // Extract and confirm the seeded signal is present.
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-gate-verify-"));
+ try {
+ const zstd = spawnSync("zstd", ["-d", "-c", out.snapshot.path], {
+ stdio: ["ignore", "pipe", "pipe"],
+ maxBuffer: 64 * 1024 * 1024,
+ });
+ expect(zstd.status).toBe(0);
+ const tar = spawnSync("tar", ["-x", "-C", tmp], {
+ input: zstd.stdout,
+ stdio: ["pipe", "inherit", "pipe"],
+ });
+ expect(tar.status).toBe(0);
+ expect(existsSync(join(tmp, "Brain", "inbox", "sig-2026-05-14-foo.md"))).toBe(true);
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/tests/core/brain/source-cleanup.test.ts b/tests/core/brain/source-cleanup.test.ts
index 046b4a03..6a6d4323 100644
--- a/tests/core/brain/source-cleanup.test.ts
+++ b/tests/core/brain/source-cleanup.test.ts
@@ -20,6 +20,7 @@
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -29,6 +30,7 @@ import { writeSignal } from "../../../src/core/brain/signal.ts";
import { writePreference } from "../../../src/core/brain/preference.ts";
import { listContinuityRecords } from "../../../src/core/brain/continuity/store.ts";
import { deleteBySource, searchBySourceFile } from "../../../src/core/brain/source-cleanup.ts";
+import { listSnapshots } from "../../../src/core/brain/snapshot.ts";
let vault: string;
@@ -251,6 +253,71 @@ describe("deleteBySource — confirmed cleanup", () => {
});
});
+describe("deleteBySource - D1 snapshot gate", () => {
+ test("confirm path snapshots before deleting and reports the recovery point", () => {
+ seedContaminatedVault();
+
+ // Learn which derived files will be deleted before running.
+ const preview = deleteBySource(vault, SOURCE, { now: NOW });
+ const derivedPaths = preview.derived.map((e) => e.path);
+ expect(derivedPaths.length).toBeGreaterThan(0);
+
+ const plan = deleteBySource(vault, SOURCE, { confirm: true, now: NOW });
+
+ // The plan carries the recovery point.
+ expect(plan.snapshotRunId).not.toBeNull();
+ expect(plan.snapshotPath).not.toBeNull();
+ expect(existsSync(plan.snapshotPath!)).toBe(true);
+
+ // A snapshot archive exists and is listed by the engine.
+ const snaps = listSnapshots(vault);
+ expect(snaps.some((s) => s.run_id === plan.snapshotRunId)).toBe(true);
+
+ // The archive is restorable: it contains the files that were deleted.
+ const tmp = mkdtempSync(join(tmpdir(), "o2b-src-snap-verify-"));
+ try {
+ const zstd = spawnSync("zstd", ["-d", "-c", plan.snapshotPath!], {
+ stdio: ["ignore", "pipe", "pipe"],
+ maxBuffer: 64 * 1024 * 1024,
+ });
+ expect(zstd.status).toBe(0);
+ const tar = spawnSync("tar", ["-x", "-C", tmp], {
+ input: zstd.stdout,
+ stdio: ["pipe", "inherit", "pipe"],
+ });
+ expect(tar.status).toBe(0);
+ // Every deleted derived path is recoverable from the archive.
+ for (const rel of derivedPaths) {
+ expect(existsSync(join(tmp, rel))).toBe(true);
+ }
+ } finally {
+ rmSync(tmp, { recursive: true, force: true });
+ }
+ });
+
+ test("dry-run takes NO snapshot", () => {
+ seedContaminatedVault();
+ const before = listSnapshots(vault).length;
+ const plan = deleteBySource(vault, SOURCE, { now: NOW });
+ expect(plan.snapshotRunId).toBeNull();
+ expect(plan.snapshotPath).toBeNull();
+ expect(listSnapshots(vault).length).toBe(before);
+ });
+
+ test("confirm with nothing to delete takes NO snapshot (no-op stays a no-op)", () => {
+ // A pristine vault with no derived material for this source.
+ const before = listSnapshots(vault).length;
+ const plan = deleteBySource(vault, "imports/does-not-exist.md", {
+ confirm: true,
+ now: NOW,
+ });
+ expect(plan.deleted).toEqual([]);
+ expect(plan.snapshotRunId).toBeNull();
+ expect(plan.snapshotPath).toBeNull();
+ expect(listSnapshots(vault).length).toBe(before);
+ });
+});
+
describe("deleteBySource — shared preference via managed _evidenced_by (CR #127.7)", () => {
test("a wikilink-matched preference evidenced by a FOREIGN signal is reported, never deleted", () => {
seedContaminatedVault();
diff --git a/tests/core/brain/write-advisory.test.ts b/tests/core/brain/write-advisory.test.ts
new file mode 100644
index 00000000..79407245
--- /dev/null
+++ b/tests/core/brain/write-advisory.test.ts
@@ -0,0 +1,157 @@
+/**
+ * A4 (t_f79b4fe0): write-time conflict advisory seam.
+ *
+ * `adviseIncomingFeedback` loads confirmed same-scope preferences, runs
+ * the pure `adviseOnIncoming` kernel, logs a `write-conflict-advisory`
+ * event, and returns the advisory (or null). It never throws into the
+ * write path: an advisory-computation failure degrades to a warning and a
+ * null result while the surrounding write still succeeds.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+import { writePreference } from "../../../src/core/brain/preference.ts";
+import { readAllLogEntries } from "../../../src/core/brain/query.ts";
+import { routeExtractedFacts } from "../../../src/core/brain/fact-extract.ts";
+import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";
+import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
+import { adviseIncomingFeedback } from "../../../src/core/brain/write-advisory.ts";
+
+let tmp: string;
+let vault: string;
+
+const NOW = new Date("2026-07-18T12:00:00Z");
+
+function confirmPref(slug: string, principle: string, scope?: string): void {
+ writePreference(vault, {
+ slug,
+ topic: slug,
+ principle,
+ created_at: NOW.toISOString(),
+ unconfirmed_until: NOW.toISOString(),
+ confirmed_at: NOW.toISOString(),
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ evidenced_by: ["[[sig-2026-07-18-seed]]"],
+ ...(scope !== undefined ? { scope } : {}),
+ });
+}
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-advisory-"));
+ vault = join(tmp, "vault");
+ const configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("adviseIncomingFeedback", () => {
+ test("returns an advisory naming a conflicting confirmed same-scope preference", () => {
+ confirmPref("tabs", "always indent source with tabs not spaces", "coding");
+ const advisory = adviseIncomingFeedback(vault, {
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ agent: "test-agent",
+ now: NOW,
+ });
+ expect(advisory).not.toBeNull();
+ expect(advisory!.scope).toBe("coding");
+ expect(advisory!.conflicts.map((c) => c.pref_id)).toEqual(["pref-tabs"]);
+ expect(advisory!.conflicts[0]!.jaccard).toBeGreaterThanOrEqual(0.5);
+ });
+
+ test("returns null for a non-conflicting incoming principle", () => {
+ confirmPref("tabs", "always indent source with tabs not spaces", "coding");
+ const advisory = adviseIncomingFeedback(vault, {
+ principle: "prefer semantic HTML over generic containers",
+ scope: "coding",
+ agent: "test-agent",
+ now: NOW,
+ });
+ expect(advisory).toBeNull();
+ });
+
+ test("does not fire across scopes", () => {
+ confirmPref("tabs", "always indent source with tabs not spaces", "coding");
+ const advisory = adviseIncomingFeedback(vault, {
+ principle: "always indent source with tabs not spaces",
+ scope: "writing",
+ agent: "test-agent",
+ now: NOW,
+ });
+ expect(advisory).toBeNull();
+ });
+
+ test("logs a write-conflict-advisory event when it fires", () => {
+ confirmPref("tabs", "always indent source with tabs not spaces", "coding");
+ adviseIncomingFeedback(vault, {
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ agent: "test-agent",
+ now: NOW,
+ });
+ const entries = readAllLogEntries(vault);
+ const advisoryEvents = entries.filter(
+ (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
+ );
+ expect(advisoryEvents.length).toBe(1);
+ const conflicts = advisoryEvents[0]!.body["conflicts"];
+ expect(Array.isArray(conflicts)).toBe(true);
+ expect((conflicts as ReadonlyArray<string>)[0]).toContain("[[pref-tabs]]");
+ });
+
+ test("degrades to a warning (returns null) when the preferences dir is unreadable", () => {
+ // Replace the preferences directory with a FILE so readdirSync throws
+ // ENOTDIR: the advisory computation must swallow the failure into a
+ // warning and return null, never propagate an exception.
+ const prefsDir = brainDirs(vault).preferences;
+ rmSync(prefsDir, { recursive: true, force: true });
+ writeFileSync(prefsDir, "not a directory");
+ // Capture stderr so we can assert the degradation is VISIBLE, not a
+ // silently-swallowed failure.
+ const originalStderrWrite = process.stderr.write.bind(process.stderr);
+ let captured = "";
+ process.stderr.write = ((chunk: string | Uint8Array): boolean => {
+ captured += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+ return true;
+ }) as typeof process.stderr.write;
+ try {
+ const advisory = adviseIncomingFeedback(vault, {
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ agent: "test-agent",
+ now: NOW,
+ });
+ expect(advisory).toBeNull();
+ expect(captured).toContain("write-conflict advisory computation failed");
+ } finally {
+ process.stderr.write = originalStderrWrite;
+ }
+ });
+
+ test("the extracted-fact path never fires the advisory (no double-fire)", () => {
+ // A confirmed preference exists that an extracted fact could resemble,
+ // but routeExtractedFacts must NOT compute the advisory - it attaches
+ // to the operator-facing feedback path only.
+ confirmPref("url", "https://techmeat.dev", "coding");
+ routeExtractedFacts(vault, {
+ facts: [{ family: "url", text: "https://techmeat.dev", line: 1 }],
+ agent: "claude-dev-agent",
+ now: NOW,
+ sessionRef: "s#1",
+ dedup: new Map<string, DedupIndexEntry>(),
+ });
+ const advisoryEvents = readAllLogEntries(vault).filter(
+ (e) => e.eventType === BRAIN_LOG_EVENT_KIND.writeConflictAdvisory,
+ );
+ expect(advisoryEvents.length).toBe(0);
+ });
+});
diff --git a/tests/core/config.test.ts b/tests/core/config.test.ts
index b1749336..6c9cb840 100644
--- a/tests/core/config.test.ts
+++ b/tests/core/config.test.ts
@@ -9,6 +9,7 @@ import {
parseSimpleYaml,
redactMapping,
resolveAgentName,
+ resolveExposeHostPaths,
resolveLinkOutputFormat,
resolveRecallAdequacyThresholds,
resolveSkillsAttachTriggers,
@@ -17,6 +18,8 @@ import {
resolveVault,
setConfigValue,
validateTimezoneName,
+ vaultStoreReference,
+ VAULT_STORE_REF_PREFIX,
} from "../../src/core/config.ts";
let tmp: string;
@@ -36,6 +39,7 @@ beforeEach(() => {
"OPEN_SECOND_BRAIN_RECALL_ADEQUACY_SUFFICIENT",
"OPEN_SECOND_BRAIN_RECALL_ADEQUACY_WEAK",
"OPEN_SECOND_BRAIN_RECALL_ADEQUACY_MIN_RESULTS",
+ "OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS",
]) {
savedEnv[k] = process.env[k];
delete process.env[k];
@@ -411,3 +415,41 @@ describe("resolveRecallAdequacyThresholds", () => {
expect(() => resolveRecallAdequacyThresholds(cfg)).toThrow();
});
});
+
+describe("resolveExposeHostPaths", () => {
+ test("defaults to false when unset", () => {
+ const cfg = join(tmp, "config.yaml");
+ writeFileSync(cfg, "vault_path: /tmp/vault\n");
+ expect(resolveExposeHostPaths(cfg)).toBe(false);
+ });
+
+ test("reads the config key", () => {
+ const cfg = join(tmp, "config.yaml");
+ writeFileSync(cfg, "expose_host_paths: true\n");
+ expect(resolveExposeHostPaths(cfg)).toBe(true);
+ });
+
+ test("env twin overrides", () => {
+ const cfg = join(tmp, "config.yaml");
+ writeFileSync(cfg, "expose_host_paths: false\n");
+ process.env["OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS"] = "true";
+ expect(resolveExposeHostPaths(cfg)).toBe(true);
+ });
+});
+
+describe("vaultStoreReference", () => {
+ test("has the vault:// prefix and 8 hex chars", () => {
+ const cfg = join(tmp, "config.yaml");
+ writeFileSync(cfg, "vault_path: /tmp/vault\n");
+ const ref = vaultStoreReference("/some/vault", cfg);
+ expect(ref.startsWith(VAULT_STORE_REF_PREFIX)).toBe(true);
+ expect(ref).toMatch(/^vault:\/\/[0-9a-f]{8}$/);
+ });
+
+ test("is stable for the same vault and differs across vaults", () => {
+ const cfg = join(tmp, "config.yaml");
+ writeFileSync(cfg, "vault_path: /tmp/vault\n");
+ expect(vaultStoreReference("/a/vault", cfg)).toBe(vaultStoreReference("/a/vault", cfg));
+ expect(vaultStoreReference("/a/vault", cfg)).not.toBe(vaultStoreReference("/b/vault", cfg));
+ });
+});
diff --git a/tests/core/search/embeddings.prefixes.test.ts b/tests/core/search/embeddings.prefixes.test.ts
new file mode 100644
index 00000000..b21c924e
--- /dev/null
+++ b/tests/core/search/embeddings.prefixes.test.ts
@@ -0,0 +1,134 @@
+import { test, expect, beforeEach, afterEach } from "bun:test";
+
+import { OpenAICompatProvider } from "../../../src/core/search/embeddings/openai-compat.ts";
+import {
+ isE5FamilyModel,
+ resolveEmbeddingPrefixes,
+ findEmbeddingPreset,
+} from "../../../src/core/search/embeddings/presets.ts";
+import type { ResolvedEmbeddingConfig } from "../../../src/core/search/types.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+
+let server: FakeHttp;
+
+function cfg(overrides: Partial<ResolvedEmbeddingConfig> = {}): ResolvedEmbeddingConfig {
+ return Object.freeze({
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "fake-model",
+ apiKey: "test-key",
+ dimension: 4,
+ timeoutMs: 5_000,
+ concurrency: 2,
+ batchSize: 32,
+ costGateUsd: 0,
+ maxRetries: 3,
+ ...overrides,
+ });
+}
+
+function captureInputHandler(captured: string[]) {
+ return (req: { body: unknown }) => {
+ const body = req.body as { input: string[]; model: string };
+ for (const t of body.input) captured.push(t);
+ const data = body.input.map((t, i) => ({
+ object: "embedding",
+ embedding: [t.length, i, 1, 1],
+ index: i,
+ }));
+ return { status: 200, body: { data, model: body.model } };
+ };
+}
+
+beforeEach(async () => {
+ server = await startFakeHttp();
+});
+
+afterEach(async () => {
+ await server.close();
+});
+
+// ── preset / structural resolution ───────────────────────────────────────────
+
+test("isE5FamilyModel matches e5 model ids structurally, not by prose", () => {
+ expect(isE5FamilyModel("intfloat/multilingual-e5-small")).toBe(true);
+ expect(isE5FamilyModel("intfloat/e5-large-v2")).toBe(true);
+ expect(isE5FamilyModel("intfloat/multilingual-e5-large-instruct")).toBe(true);
+ expect(isE5FamilyModel("BAAI/bge-m3")).toBe(false);
+ expect(isE5FamilyModel("text-embedding-3-small")).toBe(false);
+ expect(isE5FamilyModel("acme/e5x-weird")).toBe(false);
+});
+
+test("the shipped e5 preset carries the query/passage prefixes", () => {
+ const preset = findEmbeddingPreset("intfloat/multilingual-e5-small");
+ expect(preset?.queryPrefix).toBe("query: ");
+ expect(preset?.passagePrefix).toBe("passage: ");
+});
+
+test("resolveEmbeddingPrefixes defaults to the e5 prefixes for an e5 model", () => {
+ expect(resolveEmbeddingPrefixes("intfloat/multilingual-e5-small", null, null)).toEqual({
+ queryPrefix: "query: ",
+ passagePrefix: "passage: ",
+ });
+});
+
+test("resolveEmbeddingPrefixes yields empty prefixes for a non-e5 model with no config", () => {
+ expect(resolveEmbeddingPrefixes("text-embedding-3-small", null, null)).toEqual({
+ queryPrefix: "",
+ passagePrefix: "",
+ });
+ expect(resolveEmbeddingPrefixes(null, null, null)).toEqual({
+ queryPrefix: "",
+ passagePrefix: "",
+ });
+});
+
+test("config overrides win over preset defaults", () => {
+ expect(resolveEmbeddingPrefixes("intfloat/multilingual-e5-small", "q> ", "p> ")).toEqual({
+ queryPrefix: "q> ",
+ passagePrefix: "p> ",
+ });
+});
+
+test("an explicit empty-string override disables a preset prefix", () => {
+ expect(resolveEmbeddingPrefixes("intfloat/multilingual-e5-small", "", "")).toEqual({
+ queryPrefix: "",
+ passagePrefix: "",
+ });
+});
+
+// ── provider boundary ────────────────────────────────────────────────────────
+
+test("embed(texts, 'passage') prepends the configured passage prefix", async () => {
+ const captured: string[] = [];
+ server.setHandler(captureInputHandler(captured));
+ const p = new OpenAICompatProvider(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }));
+ await p.embed(["hello", "world"], "passage");
+ expect(captured).toEqual(["passage: hello", "passage: world"]);
+});
+
+test("embed(texts, 'query') prepends the configured query prefix", async () => {
+ const captured: string[] = [];
+ server.setHandler(captureInputHandler(captured));
+ const p = new OpenAICompatProvider(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }));
+ await p.embed(["find me"], "query");
+ expect(captured).toEqual(["query: find me"]);
+});
+
+test("embed(texts) with no kind sends the texts byte-identical (backward compatible)", async () => {
+ const captured: string[] = [];
+ server.setHandler(captureInputHandler(captured));
+ const p = new OpenAICompatProvider(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }));
+ await p.embed(["untouched"]);
+ expect(captured).toEqual(["untouched"]);
+});
+
+test("an empty prefix leaves the input byte-identical even when a kind is passed", async () => {
+ const captured: string[] = [];
+ server.setHandler(captureInputHandler(captured));
+ const p = new OpenAICompatProvider(cfg({ queryPrefix: "", passagePrefix: "" }));
+ await p.embed(["a"], "passage");
+ await p.embed(["b"], "query");
+ expect(captured).toEqual(["a", "b"]);
+});
diff --git a/tests/core/search/embeddings.quota.test.ts b/tests/core/search/embeddings.quota.test.ts
new file mode 100644
index 00000000..3eebc9bb
--- /dev/null
+++ b/tests/core/search/embeddings.quota.test.ts
@@ -0,0 +1,158 @@
+/**
+ * Quota/billing error classification (Task C1). HTTP 402 always denotes an
+ * exhausted embedding quota; HTTP 429 denotes quota ONLY when the response
+ * body carries a protocol-token evidence (provider error `code`/`type` such
+ * as `insufficient_quota` or a `billing_*` code). Quota errors are
+ * non-retriable and carry an actionable billing message; plain 429 stays a
+ * retriable rate-limit.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+
+import {
+ OpenAICompatProvider,
+ classifyEmbeddingError,
+} from "../../../src/core/search/embeddings/openai-compat.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import type { ResolvedEmbeddingConfig } from "../../../src/core/search/types.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+
+let server: FakeHttp;
+
+function cfg(overrides: Partial<ResolvedEmbeddingConfig> = {}): ResolvedEmbeddingConfig {
+ return Object.freeze({
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "fake-model",
+ apiKey: "test-key",
+ dimension: null,
+ timeoutMs: 5_000,
+ concurrency: 2,
+ batchSize: 32,
+ costGateUsd: 0,
+ maxRetries: 5,
+ ...overrides,
+ });
+}
+
+beforeEach(async () => {
+ server = await startFakeHttp();
+});
+
+afterEach(async () => {
+ await server.close();
+});
+
+async function embedExpectingError(p: OpenAICompatProvider): Promise<SearchError> {
+ try {
+ await p.embed(["x"]);
+ } catch (e) {
+ return e as SearchError;
+ }
+ throw new Error("expected embed to throw");
+}
+
+test("HTTP 402 classifies as EMBEDDING_QUOTA_EXHAUSTED and does not retry", async () => {
+ server.setHandler(() => ({ status: 402, body: { error: { message: "payment required" } } }));
+ const p = new OpenAICompatProvider(cfg(), { backoffMs: [1, 1] });
+ const err = await embedExpectingError(p);
+ expect(err.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(err.status).toBe(402);
+ expect(err.message).toMatch(/quota|billing/i);
+ expect(server.callCount()).toBe(1);
+});
+
+test("HTTP 402 exposes a parsed Retry-After seconds value as milliseconds", async () => {
+ server.setHandler(() => ({
+ status: 402,
+ headers: { "retry-after": "7" },
+ body: { error: { message: "payment required" } },
+ }));
+ const p = new OpenAICompatProvider(cfg(), { backoffMs: [1, 1] });
+ const err = await embedExpectingError(p);
+ expect(err.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(err.retryAfterMs).toBe(7000);
+});
+
+test("HTTP 429 with insufficient_quota body classifies as quota (no retry)", async () => {
+ server.setHandler(() => ({
+ status: 429,
+ body: { error: { code: "insufficient_quota", message: "exceeded" } },
+ }));
+ const p = new OpenAICompatProvider(cfg(), { backoffMs: [1, 1] });
+ const err = await embedExpectingError(p);
+ expect(err.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(err.status).toBe(429);
+ expect(server.callCount()).toBe(1);
+});
+
+test("HTTP 429 with a billing_* error type classifies as quota", async () => {
+ server.setHandler(() => ({
+ status: 429,
+ body: { error: { type: "billing_hard_limit_reached" } },
+ }));
+ const p = new OpenAICompatProvider(cfg(), { backoffMs: [1, 1] });
+ const err = await embedExpectingError(p);
+ expect(err.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(server.callCount()).toBe(1);
+});
+
+test("plain HTTP 429 without quota evidence stays a retriable rate-limit", async () => {
+ server.setHandler(() => ({ status: 429, body: { error: "rate limited" } }));
+ const p = new OpenAICompatProvider(cfg({ maxRetries: 2 }), { backoffMs: [1] });
+ const err = await embedExpectingError(p);
+ expect(err.code).toBe("EMBEDDING_PROVIDER_HTTP");
+ expect(err.message).toContain("429");
+ expect(server.callCount()).toBe(2);
+});
+
+test("classifyEmbeddingError maps a quota error to a non-retriable quota category", () => {
+ const e = new SearchError("EMBEDDING_QUOTA_EXHAUSTED", "billing exhausted", {
+ status: 402,
+ retryAfterMs: 5000,
+ });
+ const cls = classifyEmbeddingError(e);
+ expect(cls.category).toBe("quota");
+ expect(cls.retriable).toBe(false);
+ expect(cls.retryAfterMs).toBe(5000);
+ expect(cls.error).toBe(e);
+});
+
+test("classifyEmbeddingError maps HTTP statuses to categories", () => {
+ const cases: Array<{ status: number; category: string; retriable: boolean }> = [
+ { status: 429, category: "rate_limit", retriable: true },
+ { status: 500, category: "transient", retriable: true },
+ { status: 503, category: "transient", retriable: true },
+ { status: 401, category: "auth", retriable: false },
+ { status: 403, category: "auth", retriable: false },
+ { status: 400, category: "fatal", retriable: false },
+ ];
+ for (const c of cases) {
+ const e = new SearchError("EMBEDDING_PROVIDER_HTTP", `embedding HTTP ${c.status}`, {
+ status: c.status,
+ });
+ const cls = classifyEmbeddingError(e);
+ expect(cls.category).toBe(c.category as never);
+ expect(cls.retriable).toBe(c.retriable);
+ }
+});
+
+test("classifyEmbeddingError treats timeouts and network errors as transient", () => {
+ const timeout = new SearchError("EMBEDDING_PROVIDER_TIMEOUT", "timed out");
+ expect(classifyEmbeddingError(timeout).category).toBe("transient");
+ expect(classifyEmbeddingError(timeout).retriable).toBe(true);
+
+ // No status = network error.
+ const network = new SearchError("EMBEDDING_PROVIDER_HTTP", "network error: reset");
+ expect(classifyEmbeddingError(network).category).toBe("transient");
+ expect(classifyEmbeddingError(network).retriable).toBe(true);
+});
+
+test("classifyEmbeddingError carries the parsed Retry-After through", () => {
+ const e = new SearchError("EMBEDDING_PROVIDER_HTTP", "embedding HTTP 429", {
+ status: 429,
+ retryAfterMs: 1500,
+ });
+ expect(classifyEmbeddingError(e).retryAfterMs).toBe(1500);
+});
diff --git a/tests/core/search/embeddings.retry-after.test.ts b/tests/core/search/embeddings.retry-after.test.ts
new file mode 100644
index 00000000..a5d76d5c
--- /dev/null
+++ b/tests/core/search/embeddings.retry-after.test.ts
@@ -0,0 +1,125 @@
+/**
+ * Retry-After honoring and quota fail-fast (Task C2). The retry loop honors
+ * a provider-supplied Retry-After delay (capped) for retriable rate-limit /
+ * transient errors, while quota errors take zero retries. Pure parsing and
+ * delay-computation paths are unit-tested; end-to-end honoring is proven
+ * against the fake HTTP server.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+
+import {
+ OpenAICompatProvider,
+ computeRetryDelayMs,
+ RETRY_AFTER_CAP_MS,
+} from "../../../src/core/search/embeddings/openai-compat.ts";
+import { parseRetryAfterMs } from "../../../src/core/search/embeddings/http-util.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import type { ResolvedEmbeddingConfig } from "../../../src/core/search/types.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+
+let server: FakeHttp;
+
+function cfg(overrides: Partial<ResolvedEmbeddingConfig> = {}): ResolvedEmbeddingConfig {
+ return Object.freeze({
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "fake-model",
+ apiKey: "test-key",
+ dimension: null,
+ timeoutMs: 5_000,
+ concurrency: 2,
+ batchSize: 32,
+ costGateUsd: 0,
+ maxRetries: 5,
+ ...overrides,
+ });
+}
+
+beforeEach(async () => {
+ server = await startFakeHttp();
+});
+
+afterEach(async () => {
+ await server.close();
+});
+
+test("parseRetryAfterMs converts delta-seconds to milliseconds", () => {
+ expect(parseRetryAfterMs("5")).toBe(5000);
+ expect(parseRetryAfterMs(" 10 ")).toBe(10000);
+ expect(parseRetryAfterMs("0")).toBe(0);
+});
+
+test("parseRetryAfterMs returns null for absent or unparseable values", () => {
+ expect(parseRetryAfterMs(null)).toBeNull();
+ expect(parseRetryAfterMs("")).toBeNull();
+ expect(parseRetryAfterMs("soon")).toBeNull();
+});
+
+test("parseRetryAfterMs parses an HTTP-date relative to now", () => {
+ const now = Date.parse("2026-01-01T00:00:00Z");
+ const future = new Date(now + 12_000).toUTCString();
+ expect(parseRetryAfterMs(future, now)).toBe(12000);
+ // A past date floors at zero rather than going negative.
+ const past = new Date(now - 5_000).toUTCString();
+ expect(parseRetryAfterMs(past, now)).toBe(0);
+});
+
+test("computeRetryDelayMs honors Retry-After up to the cap", () => {
+ expect(computeRetryDelayMs(5000, 1, [1000, 2000], RETRY_AFTER_CAP_MS)).toBe(5000);
+ expect(computeRetryDelayMs(RETRY_AFTER_CAP_MS + 10_000, 1, [1000], RETRY_AFTER_CAP_MS)).toBe(
+ RETRY_AFTER_CAP_MS,
+ );
+});
+
+test("computeRetryDelayMs falls back to jittered exponential backoff", () => {
+ const first = computeRetryDelayMs(null, 1, [1000, 2000], RETRY_AFTER_CAP_MS);
+ expect(first).toBeGreaterThanOrEqual(750);
+ expect(first).toBeLessThanOrEqual(1250);
+ // Attempt beyond the array reuses the last base.
+ const later = computeRetryDelayMs(null, 5, [1000, 2000], RETRY_AFTER_CAP_MS);
+ expect(later).toBeGreaterThanOrEqual(1500);
+ expect(later).toBeLessThanOrEqual(2500);
+});
+
+test("RETRY_AFTER_CAP_MS is a sane bounded cap (30s)", () => {
+ expect(RETRY_AFTER_CAP_MS).toBe(30_000);
+});
+
+test("quota fails fast with zero retries regardless of maxRetries", async () => {
+ server.setHandler(() => ({ status: 402, body: { error: { message: "pay up" } } }));
+ const p = new OpenAICompatProvider(cfg({ maxRetries: 5 }), { backoffMs: [1, 1, 1, 1] });
+ let err: SearchError | null = null;
+ try {
+ await p.embed(["x"]);
+ } catch (e) {
+ err = e as SearchError;
+ }
+ expect(err?.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(server.callCount()).toBe(1);
+ expect(p.consumeRetryCount()).toBe(0);
+});
+
+test("rate-limit retry honors Retry-After instead of the configured backoff", async () => {
+ let calls = 0;
+ server.setHandler(() => {
+ calls++;
+ if (calls === 1) {
+ return { status: 429, headers: { "retry-after": "0" }, body: { error: "slow down" } };
+ }
+ return {
+ status: 200,
+ body: { data: [{ object: "embedding", embedding: [1, 0, 0, 0], index: 0 }], model: "m" },
+ };
+ });
+ // Backoff is 10s: if the loop used it instead of the 0s Retry-After the
+ // test would blow past its own budget.
+ const p = new OpenAICompatProvider(cfg({ maxRetries: 2, dimension: 4 }), { backoffMs: [10_000] });
+ const start = Date.now();
+ const out = await p.embed(["x"]);
+ const elapsed = Date.now() - start;
+ expect(out.length).toBe(1);
+ expect(calls).toBe(2);
+ expect(elapsed).toBeLessThan(2000);
+});
diff --git a/tests/core/search/prefix-meta.test.ts b/tests/core/search/prefix-meta.test.ts
new file mode 100644
index 00000000..0f72a954
--- /dev/null
+++ b/tests/core/search/prefix-meta.test.ts
@@ -0,0 +1,119 @@
+import { test, expect, beforeEach, afterEach } from "bun:test";
+
+import { indexVault, indexStatus } from "../../../src/core/search/indexer.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+import { sqliteVecLoadable } from "../../helpers/sqlite-vec.ts";
+import type { ResolvedEmbeddingConfig } from "../../../src/core/search/types.ts";
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+let server: FakeHttp;
+
+beforeEach(async () => {
+ const v = createTempVault("prefix-meta");
+ vault = v.vault;
+ dbPath = v.dbPath;
+ cleanup = v.cleanup;
+ server = await startFakeHttp();
+});
+
+afterEach(async () => {
+ cleanup();
+ await server.close();
+});
+
+function cfg(semantic: Partial<ResolvedEmbeddingConfig>) {
+ return makeConfig({
+ vault,
+ dbPath,
+ semantic: {
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "fake-model",
+ apiKey: "test-key",
+ dimension: 4,
+ timeoutMs: 5_000,
+ concurrency: 2,
+ batchSize: 8,
+ costGateUsd: 0,
+ maxRetries: 3,
+ ...semantic,
+ },
+ });
+}
+
+test("indexing persists the active prefix pair into index meta", async () => {
+ if (!sqliteVecLoadable()) return;
+ writeMd(vault, "a.md", "# A\n\nA note about prefixes.");
+ await indexVault(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }), {
+ embeddings: true,
+ });
+
+ const store = await Store.open(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }), {
+ mode: "read",
+ });
+ expect(store.getState("embedding_prefix_query")).toBe("query: ");
+ expect(store.getState("embedding_prefix_passage")).toBe("passage: ");
+ await store.close();
+});
+
+test("no preset match and no config records an empty prefix pair (byte-identical baseline)", async () => {
+ if (!sqliteVecLoadable()) return;
+ writeMd(vault, "a.md", "# A\n\nAnother note.");
+ await indexVault(cfg({ queryPrefix: "", passagePrefix: "" }), { embeddings: true });
+
+ const store = await Store.open(cfg({ queryPrefix: "", passagePrefix: "" }), { mode: "read" });
+ expect(store.getState("embedding_prefix_query")).toBe("");
+ expect(store.getState("embedding_prefix_passage")).toBe("");
+ await store.close();
+});
+
+test("a stored-vs-configured prefix mismatch surfaces a reindex-required warning", async () => {
+ if (!sqliteVecLoadable()) return;
+ writeMd(vault, "a.md", "# A\n\nNote embedded without a prefix.");
+ await indexVault(cfg({ queryPrefix: "", passagePrefix: "" }), { embeddings: true });
+
+ // Now the operator configures e5-style prefixes without reindexing: the
+ // stored (empty) pair no longer matches the configured pair.
+ const status = await indexStatus(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }));
+ expect(status.warnings.some((w) => /prefix/i.test(w) && /reindex/i.test(w))).toBe(true);
+});
+
+test("legacy embeddings without prefix metadata are cleared when non-empty prefixes are configured", async () => {
+ if (!sqliteVecLoadable()) return;
+ writeMd(vault, "a.md", "# A\n\nA note embedded before prefix metadata existed.");
+ await indexVault(cfg({ queryPrefix: "", passagePrefix: "" }), { embeddings: true });
+
+ // Simulate a legacy store that predates prefix metadata: strip the recorded
+ // prefix state so both keys read as absent (null), leaving unprefixed vectors.
+ const legacy = await Store.open(cfg({ queryPrefix: "", passagePrefix: "" }), { mode: "write" });
+ legacy.deleteState("embedding_prefix_query");
+ legacy.deleteState("embedding_prefix_passage");
+ expect(legacy.countEmbeddings()).toBeGreaterThan(0);
+ await legacy.close();
+
+ // Opening with non-empty E5 prefixes must treat the missing state as the
+ // empty pair, detect the change, and clear the now-incompatible vectors.
+ const upgraded = await Store.open(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }), {
+ mode: "write",
+ });
+ expect(upgraded.countEmbeddings()).toBe(0);
+ expect(upgraded.getState("embedding_prefix_query")).toBe("query: ");
+ expect(upgraded.getState("embedding_prefix_passage")).toBe("passage: ");
+ await upgraded.close();
+});
+
+test("matching stored and configured prefixes produce no prefix warning", async () => {
+ if (!sqliteVecLoadable()) return;
+ writeMd(vault, "a.md", "# A\n\nNote embedded with a prefix.");
+ await indexVault(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }), {
+ embeddings: true,
+ });
+
+ const status = await indexStatus(cfg({ queryPrefix: "query: ", passagePrefix: "passage: " }));
+ expect(status.warnings.some((w) => /prefix/i.test(w))).toBe(false);
+});
diff --git a/tests/core/search/semantic-degrade-quota.test.ts b/tests/core/search/semantic-degrade-quota.test.ts
new file mode 100644
index 00000000..177b0771
--- /dev/null
+++ b/tests/core/search/semantic-degrade-quota.test.ts
@@ -0,0 +1,87 @@
+/**
+ * Graceful semantic degrade on quota/rate-limit (Task C2). Implicit semantic
+ * search (no explicit `--semantic`) degrades to keyword-only with a warning
+ * that names the classification category and, for quota, the actionable
+ * billing message. An explicit request keeps throwing the typed error and
+ * never silently falls back.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+
+import { runSemanticPhase } from "../../../src/core/search/semantic-phase.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import type { Store } from "../../../src/core/search/store.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import { startFakeHttp, type FakeHttp } from "../../helpers/fake-http.ts";
+
+let server: FakeHttp;
+
+beforeEach(async () => {
+ server = await startFakeHttp();
+});
+
+afterEach(async () => {
+ await server.close();
+});
+
+/** Minimal Store stub: enough surface for runSemanticPhase to reach embed. */
+function fakeStore(): Store {
+ return {
+ counts: () => ({ documents: 1, chunks: 1, embeddings: 1, staleEmbeddings: 0 }),
+ vecLoaded: () => true,
+ semanticTopK: () => [],
+ } as unknown as Store;
+}
+
+function semanticConfig(overrides: Record<string, unknown> = {}) {
+ return makeConfig({
+ vault: "/tmp/does-not-matter",
+ dbPath: "/tmp/does-not-matter/db.sqlite",
+ semantic: {
+ enabled: true,
+ provider: "openai-compat",
+ baseUrl: server.url,
+ model: "m",
+ apiKey: "k",
+ maxRetries: 1,
+ ...overrides,
+ },
+ });
+}
+
+test("implicit semantic degrades with a quota warning carrying the actionable message", async () => {
+ server.setHandler(() => ({ status: 402, body: { error: { message: "pay up" } } }));
+ const out = await runSemanticPhase(fakeStore(), semanticConfig(), "q", {
+ limit: 10,
+ pathPrefix: undefined,
+ explicit: false,
+ });
+ expect(out.attempted).toBe(false);
+ expect(out.warnings.some((w) => w.includes("quota") && w.includes("billing"))).toBe(true);
+});
+
+test("implicit semantic degrade names the rate_limit category", async () => {
+ server.setHandler(() => ({ status: 429, body: { error: "slow down" } }));
+ const out = await runSemanticPhase(fakeStore(), semanticConfig(), "q", {
+ limit: 10,
+ pathPrefix: undefined,
+ explicit: false,
+ });
+ expect(out.attempted).toBe(false);
+ expect(out.warnings.some((w) => w.includes("rate_limit"))).toBe(true);
+});
+
+test("explicit semantic throws the typed quota error and never falls back", async () => {
+ server.setHandler(() => ({ status: 402, body: { error: { message: "pay up" } } }));
+ let err: SearchError | null = null;
+ try {
+ await runSemanticPhase(fakeStore(), semanticConfig(), "q", {
+ limit: 10,
+ pathPrefix: undefined,
+ explicit: true,
+ });
+ } catch (e) {
+ err = e as SearchError;
+ }
+ expect(err?.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+});
diff --git a/tests/core/search/store.vec.test.ts b/tests/core/search/store.vec.test.ts
index 6dec9f2d..0753e2fd 100644
--- a/tests/core/search/store.vec.test.ts
+++ b/tests/core/search/store.vec.test.ts
@@ -213,6 +213,74 @@ test("ensureEmbeddingModel drops chunk_vec when dimension changes", async () =>
await store.close();
});
+test("a NaN vector cannot reach the vec table through vecUpsert", async () => {
+ if (!sqliteVecLoadable()) return;
+ const store = await Store.open(semanticConfig("m1", 4), { mode: "write" });
+ const docId = store.upsertDocument({
+ path: "vec/nan.md",
+ title: null,
+ contentHash: "h",
+ mtime: 0,
+ size: 1,
+ });
+ const [c0] = store.replaceChunks(docId, [
+ {
+ chunkIndex: 0,
+ content: "x",
+ contentHash: "h0",
+ startLine: 1,
+ endLine: 1,
+ tokenCount: 1,
+ },
+ ]);
+ expect(() => store.vecUpsert(c0!, [Number.NaN, 0, 0, 0], "m1", 4, "eh")).toThrow(
+ /EMBEDDING_INVALID_VECTOR|vecUpsert/,
+ );
+ const rows = store.rawQuery<{ c: number }>("SELECT count(*) AS c FROM chunk_vec");
+ expect(rows[0]?.c).toBe(0);
+ await store.close();
+});
+
+test("an all-zero vector cannot reach the vec table through vecUpsert", async () => {
+ if (!sqliteVecLoadable()) return;
+ const store = await Store.open(semanticConfig("m1", 4), { mode: "write" });
+ const docId = store.upsertDocument({
+ path: "vec/zero.md",
+ title: null,
+ contentHash: "h",
+ mtime: 0,
+ size: 1,
+ });
+ const [c0] = store.replaceChunks(docId, [
+ {
+ chunkIndex: 0,
+ content: "x",
+ contentHash: "h0",
+ startLine: 1,
+ endLine: 1,
+ tokenCount: 1,
+ },
+ ]);
+ expect(() => store.vecUpsert(c0!, [0, 0, 0, 0], "m1", 4, "eh")).toThrow(/zero/i);
+ const rows = store.rawQuery<{ c: number }>("SELECT count(*) AS c FROM chunk_vec");
+ expect(rows[0]?.c).toBe(0);
+ await store.close();
+});
+
+test("semanticTopK rejects a non-finite query vector before querying", async () => {
+ if (!sqliteVecLoadable()) return;
+ const store = await Store.open(semanticConfig("m1", 4), { mode: "write" });
+ expect(() => store.semanticTopK([Number.POSITIVE_INFINITY, 0, 0, 0], { limit: 5 })).toThrow(
+ /semanticTopK|EMBEDDING_INVALID_VECTOR/,
+ );
+ // An all-zero query vector has no direction for cosine similarity and must
+ // be rejected before querying, exactly as vecUpsert rejects it.
+ expect(() => store.semanticTopK([0, 0, 0, 0], { limit: 5 })).toThrow(
+ /zero|semanticTopK|EMBEDDING_INVALID_VECTOR/,
+ );
+ await store.close();
+});
+
test("dimension mismatch is rejected on vecUpsert", async () => {
if (!sqliteVecLoadable()) return;
const store = await Store.open(semanticConfig("m1", 4), { mode: "write" });
diff --git a/tests/core/search/types.test.ts b/tests/core/search/types.test.ts
index 57c62d1a..7ad2e8c9 100644
--- a/tests/core/search/types.test.ts
+++ b/tests/core/search/types.test.ts
@@ -13,3 +13,19 @@ test("SearchError preserves stack trace", () => {
const err = new SearchError("INVALID_INPUT", "bad");
expect(err.stack).toContain("SearchError");
});
+
+test("SearchError exposes optional status and retryAfterMs fields", () => {
+ const err = new SearchError("EMBEDDING_QUOTA_EXHAUSTED", "billing exhausted", {
+ status: 402,
+ retryAfterMs: 5000,
+ });
+ expect(err.code).toBe("EMBEDDING_QUOTA_EXHAUSTED");
+ expect(err.status).toBe(402);
+ expect(err.retryAfterMs).toBe(5000);
+});
+
+test("SearchError leaves status and retryAfterMs undefined for the two-arg form", () => {
+ const err = new SearchError("INDEX_MISSING", "no index");
+ expect(err.status).toBeUndefined();
+ expect(err.retryAfterMs).toBeUndefined();
+});
diff --git a/tests/core/search/vector-guard.test.ts b/tests/core/search/vector-guard.test.ts
new file mode 100644
index 00000000..7a6ad449
--- /dev/null
+++ b/tests/core/search/vector-guard.test.ts
@@ -0,0 +1,68 @@
+import { test, expect } from "bun:test";
+
+import { assertValidVector } from "../../../src/core/search/vector-guard.ts";
+import { unitNormaliseInPlace } from "../../../src/core/search/embeddings/http-util.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+
+test("assertValidVector accepts a finite, non-zero vector", () => {
+ expect(() => assertValidVector([0.1, 0, -0.3, 1], "unit-test")).not.toThrow();
+ expect(() => assertValidVector(Float32Array.from([0, 0, 1]), "unit-test")).not.toThrow();
+});
+
+test("assertValidVector rejects a NaN component with the context and index", () => {
+ try {
+ assertValidVector([1, Number.NaN, 3], "vecUpsert");
+ throw new Error("expected throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(SearchError);
+ const err = e as SearchError;
+ expect(err.code).toBe("EMBEDDING_INVALID_VECTOR");
+ expect(err.message).toContain("vecUpsert");
+ expect(err.message).toContain("1"); // offending index
+ }
+});
+
+test("assertValidVector rejects an Infinity component", () => {
+ const call = () => assertValidVector([0, Number.POSITIVE_INFINITY], "semanticTopK");
+ expect(call).toThrow(SearchError);
+ expect(call).toThrow(/semanticTopK/);
+});
+
+test("assertValidVector rejects an all-zero vector", () => {
+ try {
+ assertValidVector([0, 0, 0, 0], "vecUpsert");
+ throw new Error("expected throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(SearchError);
+ expect((e as SearchError).code).toBe("EMBEDDING_INVALID_VECTOR");
+ expect((e as SearchError).message).toMatch(/zero/i);
+ }
+});
+
+test("assertValidVector rejects an empty vector", () => {
+ const call = () => assertValidVector([], "vecUpsert");
+ expect(call).toThrow(SearchError);
+ expect(call).toThrow(/empty/i);
+});
+
+test("unitNormaliseInPlace throws EMBEDDING_INVALID_VECTOR on zero-norm input", () => {
+ try {
+ unitNormaliseInPlace([0, 0, 0]);
+ throw new Error("expected throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(SearchError);
+ expect((e as SearchError).code).toBe("EMBEDDING_INVALID_VECTOR");
+ }
+});
+
+test("unitNormaliseInPlace throws on non-finite input", () => {
+ const call = () => unitNormaliseInPlace([1, Number.NaN, 2]);
+ expect(call).toThrow(SearchError);
+ expect(call).toThrow(/EMBEDDING_INVALID_VECTOR|unitNormalise/i);
+});
+
+test("unitNormaliseInPlace still normalises a valid vector to unit length", () => {
+ const v = unitNormaliseInPlace([3, 4]);
+ const norm = Math.hypot(...v);
+ expect(norm).toBeCloseTo(1, 10);
+});
diff --git a/tests/mcp/brain.test.ts b/tests/mcp/brain.test.ts
index c574824a..fb4c40f1 100644
--- a/tests/mcp/brain.test.ts
+++ b/tests/mcp/brain.test.ts
@@ -198,6 +198,55 @@ describe("brain_feedback", () => {
expect(text).toContain("topic: imperative-prompts");
});
+ test("write-conflict advisory: names a confirmed same-scope preference and the write still proceeds", async () => {
+ const server = makeServer();
+ await initialize(server);
+ // Seed a confirmed same-scope preference.
+ await call(server, "brain_feedback", {
+ topic: "tabs-rule",
+ signal: "positive",
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ force_confirmed: true,
+ });
+ // A near-duplicate incoming signal in the same scope.
+ const r = await call(server, "brain_feedback", {
+ topic: "tabs-again",
+ signal: "negative",
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ });
+ expect(r.result.isError).toBe(false);
+ const s = r.result.structuredContent;
+ // The write always proceeds.
+ expect(s.signal_id).toMatch(/^sig-/);
+ // The advisory names the confirmed preference.
+ expect(s.advisory).toBeDefined();
+ expect(s.advisory.conflicts.map((c: { pref_id: string }) => c.pref_id)).toContain(
+ "pref-tabs-rule",
+ );
+ });
+
+ test("no advisory field for a non-conflicting write", async () => {
+ const server = makeServer();
+ await initialize(server);
+ await call(server, "brain_feedback", {
+ topic: "tabs-rule",
+ signal: "positive",
+ principle: "always indent source with tabs not spaces",
+ scope: "coding",
+ force_confirmed: true,
+ });
+ const r = await call(server, "brain_feedback", {
+ topic: "semantic-html",
+ signal: "positive",
+ principle: "prefer semantic HTML over generic containers",
+ scope: "coding",
+ });
+ expect(r.result.isError).toBe(false);
+ expect(r.result.structuredContent.advisory).toBeUndefined();
+ });
+
test("INVALID_PARAMS when required field missing", async () => {
const server = makeServer();
await initialize(server);
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index ffd1c2ee..dbab8d01 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -321,7 +321,7 @@ describe("tool listing", () => {
});
describe("tool calls", () => {
- test("second_brain_status reports vault and config", async () => {
+ test("second_brain_status returns an opaque store reference by default", async () => {
const vault = join(tmp, "vault");
mkdirSync(vault);
const config = join(tmp, "config.yaml");
@@ -330,12 +330,42 @@ describe("tool calls", () => {
await initialize(server);
const r = (await callTool(server, "second_brain_status"))! as any;
const s = r.result.structuredContent;
- expect(s.vault_path).toBe(vault);
+ // Default (expose_host_paths unset): the absolute host path is redacted
+ // to a stable opaque reference, never the raw path.
+ expect(s.vault_path).toMatch(/^vault:\/\/[0-9a-f]{8}$/);
+ expect(s.vault_path).not.toBe(vault);
+ // The raw host path must not leak through any field, including nested
+ // ones like config.vault_path.
+ expect(JSON.stringify(s)).not.toContain(vault);
expect(s.vault_exists).toBe(true);
expect(s.config.api_key).toBe("[REDACTED]");
expect(s.config_keys).toContain("vault_path");
});
+ test("the store reference is stable across calls for the same vault", async () => {
+ const vault = join(tmp, "vault");
+ mkdirSync(vault);
+ const config = join(tmp, "config.yaml");
+ writeFileSync(config, "vault_path: /tmp/vault\n");
+ const server = new MCPServer({ vault, configPath: config });
+ await initialize(server);
+ const a = ((await callTool(server, "second_brain_status"))! as any).result.structuredContent;
+ const b = ((await callTool(server, "second_brain_status"))! as any).result.structuredContent;
+ expect(a.vault_path).toBe(b.vault_path);
+ });
+
+ test("expose_host_paths=true restores the raw absolute path", async () => {
+ const vault = join(tmp, "vault");
+ mkdirSync(vault);
+ const config = join(tmp, "config.yaml");
+ writeFileSync(config, "vault_path: /tmp/vault\nexpose_host_paths: true\n");
+ const server = new MCPServer({ vault, configPath: config });
+ await initialize(server);
+ const r = (await callTool(server, "second_brain_status"))! as any;
+ const s = r.result.structuredContent;
+ expect(s.vault_path).toBe(vault);
+ });
+
test("second_brain_status includes a `brain` section with counts and activity", async () => {
const vault = join(tmp, "vault");
mkdirSync(vault);
diff --git a/tests/mcp/search-error-mapping.test.ts b/tests/mcp/search-error-mapping.test.ts
new file mode 100644
index 00000000..f40138ee
--- /dev/null
+++ b/tests/mcp/search-error-mapping.test.ts
@@ -0,0 +1,22 @@
+/**
+ * MCP error mapping (Task C2). An exhausted embedding quota surfaces to MCP
+ * callers as the actionable billing message rather than a generic provider
+ * failure.
+ */
+
+import { test, expect } from "bun:test";
+
+import { searchErrorToMcp } from "../../src/mcp/search-tools.ts";
+import { EMBEDDING_QUOTA_MESSAGE, SearchError } from "../../src/core/search/types.ts";
+import { INTERNAL_ERROR } from "../../src/mcp/protocol.ts";
+
+test("EMBEDDING_QUOTA_EXHAUSTED maps to the actionable billing message", () => {
+ const mcp = searchErrorToMcp(new SearchError("EMBEDDING_QUOTA_EXHAUSTED", "internal detail"));
+ expect(mcp.code).toBe(INTERNAL_ERROR);
+ expect(mcp.message).toBe(EMBEDDING_QUOTA_MESSAGE);
+});
+
+test("a generic provider HTTP error keeps its own message", () => {
+ const mcp = searchErrorToMcp(new SearchError("EMBEDDING_PROVIDER_HTTP", "embedding HTTP 500"));
+ expect(mcp.message).toContain("embedding HTTP 500");
+});