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: private is not a suggestion (v1.54.0) (#183)

Sol Aitkendc5525905599
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index ed3ac2d4..9c572444 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.53.1",
+ "version": "1.54.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 ac0943c1..86896b94 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.53.1",
+ "version": "1.54.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/.gitignore b/.gitignore
index 1a296f78..1e64c7b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,7 @@ sandbox-vault/
# Local Kanban/git worktrees (never committed; exclude from lint/fmt)
.worktrees/
.code-ranker/
+
+# Agentic-playbooks runner artifacts (never committed; exclude from lint/fmt)
+.apb/runs/
+.apb/tmp/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef2391a4..61059d80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,46 @@ 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.54.0] - 2026-08-27
+
+Open Second Brain has shipped a `visibility:` frontmatter field, a predicate that reads it, and a filter that applies it - and until this release the field was decorative. The filter was wired into exactly one call site, and the scope it filtered against came from the caller, so a remote caller that asked for the private scope was handed it. Of the 71 callable surfaces the project's own visibility census enumerated, 3 consulted the field and 68 did not. The previous wave measured that rather than closing it: 1.52.0 shipped the census, the registry behind it, and an `o2b search check` finding that stated in the operator's own diagnostics that this boundary did not exist. This release is the enforcement that census was built as the coverage map for. One reserved token is denied by default at remote reach and enforced at the three roots every read surface reaches page content through - the ranked search pipeline, the page walker, and the by-path and by-chunk-id read primitives - and a new sweep proves mechanically that there is no fourth root. The reach that decides is minted by the transport and refused by name when a caller supplies it, because a trust claim echoed back from the request is not a trust claim. A vault that never wrote the token sees no change at all, and the schema-12 backfill is what guarantees that rather than an assumption.
+
+Both source cards had premises refuted against the live source before anything was designed, and the verdicts ship as deliverables rather than as obstacles that were quietly designed around. The first card's claim that no `visibility:` handling existed in the read surfaces is refuted by `src/core/graph/visibility.ts` and `src/core/search/result-filters.ts`, and the carrier it proposed - extending `gatedOwnerScopeView` - is refused as an approach: that view short-circuits every predicate to true unless `integrity.owner_scope_delivery` is set to `fail`, so riding it would have shipped privacy that is off in every default install. The second card's claim that no registry-driven harness and no fail-closed gate existed is refuted by the agent-scope matrix and the surface census, both of which already fail on an unclassified newcomer; what survives is that the harness's axis is ownership rather than visibility, which is the axis this release adds. The wave's own stated risk is corrected too: `indexRevision` is a query-cache generation counter consumed by `computeCorpusGeneration`, not a schema or index-format revision, and moving it forces no reindex on anyone.
+
+### Added
+
+- **One reserved visibility token, denied by default at remote reach.** `isRemotelyReadable` is the kernel the rest of the wave consumes: it denies exactly one token - `REMOTE_DENY_VISIBILITY_TOKEN`, written once in the normal form `pageVisibility` reads tags into, so a page cannot spell it a second way and mean something else - and answers true for everything else at every reach. Every other token, reserved-adjacent or not, keeps the caller-liftable semantics `isVisible` has always given it; this constant reserves one identifier and defines no policy for any other. The caller's own `visibility` argument still works and can still narrow. What it can no longer do is name the reserved token and be handed the page. There is no configuration key to switch this on, because a boundary an operator has to enable is the defect the previous release's honesty finding named.
+- **The reach a request arrived at is minted by the transport and refused from the caller.** `TransportReach` is a closed two-member vocabulary - `local` and `remote` - and it is a transport fact rather than a request field. stdio and the CLI mint `local` because the caller already started the process and holds whatever filesystem access it runs with; an HTTP bind mints from `isLoopbackHost` alone, keyed on the bind rather than on a caller-supplied `Host` header, so every non-loopback bind is `remote`. Each value is set after the caller's runtime options are spread, the same guard `sendNotification` already uses, so a runtime option cannot claim a reach the bind did not establish. A caller that puts a reach-shaped argument in a `tools/call` is refused with `-32602` and the token `caller-supplied-reach`, ahead of the unknown-argument gate and without consulting the tool's schema, so an open schema is covered too; names are compared case-folded and separator-free, so `reach`, `Reach`, `transport_reach`, `transport-reach` and `transportReach` are one argument rather than five holes. `disclosure` is deliberately not reserved - it is the unrelated result-depth mode on the recall surfaces. What the `local` bypass proves is written down where it is defined rather than overclaimed: filesystem-equivalent access, or a request that originated on this host. It does not prove operator intent, since a remote host can spawn a stdio subprocess. The alternative - no bypass at all - would take an operator's private notes away from the operator's own shell.
+- **Enforcement at three read roots, and a sweep that proves there is no fourth.** Root A is the ranked pipeline, where `applyVisibilityScope` is reimplemented on the predicate rather than left beside it, and the reach rides on `SearchOptions.transportReach` with an absent value resolving to the narrowest. Root B is `listVaultPages`, where the reach is a required option rather than a defaulted one - the two ways to get it wrong fail in opposite directions - so each of its 23 call sites states which caller it walks for and the compiler is what asks the question; the maintenance lanes answer once, through `MAINTENANCE_LANE_REACH`, because a repair lane that stopped seeing reserved pages would corrupt the link graph it repairs. Root C is the key-addressed reads, where both key spaces are enumerable - a chunk id is a sequential integer and a preference id is a topic slug - so a withheld read answers with the message an absent one produces, byte for byte, rather than with a distinguishable refusal that would be an existence oracle over exactly the population being hidden. `DIRECT_VAULT_READ_REGISTRY` and its architecture sweep make the closure claim checkable instead of prose: every file under `src/mcp/`, `src/cli/` and `src/openclaw/` that opens a vault path through `node:fs` rather than a root must carry a row with a closed category and a written reason, and the sweep fails in both directions. It found two on its first run - `brain_clusters` listing `Brain/clusters/*.md` and `brain_bridges` reading `Brain/proposals/bridges.md` - and both now ask the rule at the site of the read. What the sweep cannot see is written down beside it rather than implied.
+- **`documents.visibility`: what the index measured, backfilled by schema 12.** Three distinct states - a JSON array of the page's normalised tokens, `[]` for a page that declares none, and NULL for a document the index holds no frontmatter chunk for. The backfill is the whole of why this is more than an `ALTER TABLE`: a column added without one is NULL for every existing row, and the only fail-closed reading of unmeasured is reserved, which would withhold every document in every vault on upgrade. The frontmatter is already in the index as its own chunk at `chunk_index = 0`, so the backfill is one table scan and a parse per document with no vault walk and no operator action. The design's open question is answered by measurement: it runs inside the migration transaction, and not for speed - 86 ms over 5000 documents, against 8.9 seconds to index the same corpus - but for atomicity, since a half-filled column leaves measurable rows reading as unmeasured. The column reports and the live file decides: moving the read boundary onto the column would trade promptness for a saved frontmatter read, so a page reserved a minute ago would stay readable until the next index run. What the column earns is exactness - `anyVisibilityTagPresent` was a `LIKE '%visibility:%'` scan that read a quoted key or a body line as a tagged vault, and both false positives are gone - plus the two populations `o2b search check` now reports rather than absorbs.
+- **The OpenClaw page walker joins the boundary and the census.** `src/openclaw/index.ts` was the one surface the previous census named as un-swept, which meant the place already identified as a gap was the place the sweep could not have found it. Its page search takes the narrowest reach, and the distinction from the CLI is the caller rather than the machine: a CLI verb is typed by the operator, while these tools are called by a model over a conversation the plugin cannot see. `second_brain_query`'s `total_pages` is now counted after the filter, closing a difference between `total_pages` and `returned` that the status-scope filter had already made observable.
+
+### Changed
+
+- **The `o2b search check` visibility finding states what is now true.** It used to say the field was a caller-supplied view filter and not a privacy boundary, which was true and is not any more. It now reports the three things an operator needs in order to size the change rather than infer it from a search that came back shorter: how many indexed documents reserve themselves against remote reads, how many of the enumerated note-returning surfaces still do not consult the field, and how many documents the index holds no measurable frontmatter for - reported rather than folded into "declares nothing". Every number is read at render time off the registry and off the index's own column; none is written down here. The finding fires whenever there is something to be honest about, which includes an index whose column is NULL for every row - the state that count exists to surface, and the state in which an earlier gating bug printed no line at all.
+- **The visibility registry reclassifies, and the counts fall out of it.** 24 of the 76 enumerated callable surfaces now consult the field, up from 3 of 71: 13 MCP tools, 7 CLI verbs and the 4 templated `osb://` readers, each with a written reason naming which root covers it. The 52 that remain are the honest remainder, each carrying what it actually discloses rather than being waved through. The `index_store` row is kept and reworded rather than dropped: a reserved page's text is still in `chunks` and `chunk_fts`, deliberately, because excluding it would take an operator's private notes out of the operator's own local search. That is the same trust boundary as the vault's own Markdown files, and this release does not close it.
+
+### Fixed
+
+- **The query cache is partitioned by the reach that computed it.** `buildCacheKey` enumerates every result-affecting option explicitly, and the reach became one the moment it decided which pages are in the pool. It was not in the key, so a `local` outcome and a `remote` outcome collided on one row of the shared `query_cache` table that the operator's CLI and the HTTP server both write: whichever warmed the row first served the other, handing a remote caller the reserved pages it had just been denied, and poisoning the operator's own shell in the reverse direction. Folded in resolved rather than raw, and unconditionally, because every row written before this boundary existed was computed without it.
+- **The retrieval trail stopped counting withheld rows.** `scope-filters-dropped-rows` rides out on every `brain_search` response and is not gated behind `explain`. Its baseline was taken in front of both rules, so a remote caller searching a term nobody public wrote about got zero results and a trail saying two rows had been removed - an existence oracle enumerable one query term at a time. The two rules are separate functions now, the reach rule runs first, and the trail's baseline is taken between them, so the number it publishes is exactly what the caller's own arguments removed. The assembly's one-shot backfill keeps the other count in its own field, because a reserved page crowding a narrow rank cap still has to widen the window.
+- **The successor pull-in re-asks the rule.** Relation polarity runs after the pool filters and does not only reorder: it resolves typed `superseded_by` edges to documents that were never in the filtered pool, fetches their chunks, and appends them with full path, title and content. A public page declaring a reserved successor was therefore a route to that successor's body, and the pool filter could not have caught it because the row was not in the pool. Root A is asked again over the whole pool. The identical gap for the caller's own `visibility` scope and `agentScope` predates this boundary and is recorded at the seam rather than silently carried.
+- **A caller-supplied benchmark is scored at the caller's reach.** `runRecallBenchmark` pinned `local` on every search it made under a comment calling itself an internal lane. It is not one - `dataset` is a required argument of `brain_benchmark` and `brain_tune`, both callable over any transport. The reach is an option now, resolving to the narrowest when absent. The reported premise is refuted and recorded rather than dropped: a tagged page is outside every benchmark run at every reach because the benchmark passes no visibility scope, so the observable effect is the unmeasurable page - a document still in the index whose file was deleted or made unreadable - and that is what the pinned tests measure. `captureRecallFeedback` had the same defect in sharper form, re-running the judged query unscoped and returning `resultFound`.
+- **Root B fails closed on a page it could not read.** Roots A and C substitute the reserved token for a page whose file cannot be read, on the stated ground that an unreadable visibility claim is not the absence of one. Root B decided off the parsed map alone, and the parser resolves an unreadable file to an empty map - byte-indistinguishable from a page that declares nothing - so `listVaultPages` listed it at remote reach with its path and its filename-derived title. The trigger is routine rather than exotic: a page deleted, renamed, moved to a failing mount or made unreadable between one call and the next. Toggling a reserved page's readability was itself the oracle. The walk now carries the read verdict beside the parsed map and substitutes the same token its twin does, spelled from the same exported constant so the two cannot drift.
+- **Two counts that reported what they had withheld.** `brain_query mode=topic` filtered its signals and log events and then reported the pre-filter count - a number written to the recall-telemetry log and handed back verbatim by `brain_recall_telemetry`, so a caller that saw an empty topic could read through a second tool how many rows it had been withheld from. `brain_clusters operation=run` reported community membership filtered by owner scope alone; both rules are ANDed now, and a community either rule withholds is dropped whole, because a community of seven reported as four is not a narrower true finding but a false one.
+- **A withheld preference names the id an absent one names.** Both refusals claimed byte-identity with the absent form in their own comments and neither had it. `brain_query mode=preference` passed an already-formatted sentence into a constructor that formats the sentence itself, and `osb://preference/{id}` echoed the raw id on the withheld branch while the absent branch rethrew the normalised one - so for the bare-slug key shape the presence of the `pref-` prefix was a one-bit existence oracle over the whole reserved population. Both key shapes are pinned on both surfaces now.
+- **`brain_bridges` and `brain_backlinks` ask the rule about what they name, not only about what they return.** `brain_bridges` was classified covered off its `list` mode alone, while `discover` returned proposals naming two pages each by vault-relative path; a proposal is dropped whole when either end is withheld. `brain_backlinks` and its CLI mirror published every ref the index returned, and a ref names its source artifact, so a withheld target now answers with the empty backlink document and a visible target no longer names sources the caller may not see.
+- **The reference grammar stopped failing open on spelling and on shape.** A reference the resolver could not place was read as naming nothing and let its row through - a fail-open on a rule whose whole posture is fail-closed. Three cases were live: aliased, anchored and line-ranged forms such as `pref-x|alias` and `pref-x#Raw`, which `brain_apply_evidence` documents for its own `artifact` argument; multi-artifact payload values, which are `string | ReadonlyArray<string>` and answered undefined as arrays; and an enumeration of four payload keys where a census of every `appendLogEvent` body in the tree finds artifact references under thirteen. Every string in the payload is offered now, because enumerating a payload whose writers are open-ended is the defect rather than the particular keys that were missing, and offering too much is safe in the way offering too little is not.
+- **Two surfaces that were outside the denominator.** The census sweeps a file only when it imports a note-content primitive directly, and `brain_hygiene` and `brain_skill_proposals` reach page content through a `src/core/` helper - so neither had a registry row, neither was in the number `o2b search check` reports, and both were returning reserved page paths at remote reach. Both are filtered at the handler seam the owner rule already sits on, so a hygiene detector registered later inherits the rule, and both recompute their own count from the visible rows.
+
+### Notes
+
+- What this release deliberately does not close is stated rather than implied. A reserved page's body stays in the index, so anyone with file access to `brain.sqlite` reads it - the same trust boundary as the vault's Markdown files. Owner-scope delivery and this boundary remain independent rules over different subjects, and neither is folded into the other. Non-reserved tokens keep exactly today's caller-liftable semantics. And 52 enumerated surfaces still do not consult the field; the visibility matrix measures which of them can still name a reserved page at remote reach and asserts that list in both directions, so a surface leaving it is the wave that covered it and one joining it is a regression.
+- The design called the closed vocabulary `disclosure`. That word was already taken in this tree - `SearchOptions.disclosure` is the progressive result-depth mode - and this value rides on the same options bag, so the transport fact is named for what it measures instead. Two fields with one name meaning different things is the defect this suite exists to remove.
+- The new visibility matrix is a sibling of the owner matrix rather than a second axis inside it, decided on evidence the design left open: the two cannot share one fixture, because the owner matrix builds its contexts without a reach and every one of its assertions would have had to say which reach it was asking at. The recipes are shared through one catalogue rather than copied, since a second copy of "what is the whole surface" is the enumeration defect the first matrix was built to remove. Every probe goes through the real `tools/call` path and asserts over the whole serialised response, which covers `structuredContent`, the rendered text, a thrown `message` and the `_meta` member in one check.
+- One recorded limit on the new column: an unterminated frontmatter block is measured as declaring nothing rather than as unmeasured, because the chunker leaves chunk zero of such a page byte-indistinguishable from that of a page with no frontmatter. It does not matter, because the live parse on the real file reads an unterminated block the same way - the column and the boundary agree rather than one of them being wrong in private.
+- A pre-existing test flake was root-caused and fixed on the way. `dream progress > attaching an observer changes nothing the pass writes` failed about once in twelve loaded runs and never in isolation; the whole difference was the snapshot entry's `size_bytes`, republished into the day log the assertion compares, and whether it tripped depended on whether the copy straddled a second. Verified against `main`'s own source at the same rate before being fixed by normalising the one field rather than excluding the pass's main authored artifact.
+
## [1.53.1] - 2026-08-27
Reported as [#180](https://github.com/itechmeat/open-second-brain/issues/180) by [@BlackKite84](https://github.com/BlackKite84): `o2b brain page-dedup` merges a duplicate pair, stamps `merged_into` on the secondary, and then proposes the same merge again on the next scan, forever. Confirmed as filed, and the seam the report named - `findDuplicateCandidates`, which never read the pointer the merge writes - is the right one; it is the single chokepoint behind `page-dedup`, `brain actions`, the digest, `brain_doctor`, `vault_health` and the operator trust verdict, so one filter closes all six. Verification found two escalations the report did not mention, and both raise this from a noisy digest to a silent vault mutation: on pages with no `created_at` the canonical ordering falls back to an mtime the merge itself moves, so a second `--apply` reverses the pair and writes a merge CYCLE that leaves `lint --consolidate` unable to repair any link to either page; and `setMergedInto` overwrote an existing `merged_into` without asking, so a deliberate operator merge was repointed at whatever canonical the next run picked. One side-claim in the report is rejected: identical text under different scopes cannot re-collapse, because the composite scope is already folded into the dedup key and a test has pinned that since v1.37.0.
@@ -7388,6 +7428,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.54.0]: https://github.com/itechmeat/open-second-brain/compare/v1.53.1...v1.54.0
[1.53.1]: https://github.com/itechmeat/open-second-brain/compare/v1.53.0...v1.53.1
[1.53.0]: https://github.com/itechmeat/open-second-brain/compare/v1.52.1...v1.53.0
[1.52.1]: https://github.com/itechmeat/open-second-brain/compare/v1.52.0...v1.52.1
diff --git a/README.md b/README.md
index 0829e067..b88999e5 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,15 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
## What is new
-Open Second Brain 1.52.0 is the honesty wave: nothing writes silently, nothing degrades silently. Nine tracker cards were read against the live source before anything was designed, and the reading did most of the work - one card described a feature that had already shipped end to end, one asked for privacy by riding a predicate that is inert in every default install, and four more had premises the source contradicted. What survived is one rule applied eight ways.
+Open Second Brain 1.54.0 turns `visibility:` from a label into a boundary. The field, the predicate that reads it and the filter that applies it have all shipped for several releases, and until now the filter was wired into one call site and the scope it filtered against came from the caller - so a remote caller that asked for the private scope was handed it. One reserved token is now denied by default at remote reach, enforced at the three roots every read surface reaches page content through: the ranked search pipeline, the page walker, and the by-path and by-chunk-id read primitives. An architecture sweep proves mechanically that there is no fourth root, and it found two direct filesystem reads on its first run.
-A note update now refuses to destroy what it could not read - an unreadable note raises `target_unreadable` instead of parsing as empty, and a blank body over a non-empty note needs an explicit `allow_empty`. `o2b search check` measures instead of inferring: a real pending-vector count replaces a recommendation that told fully embedded vaults to compute their first vectors, an embedder record audit reports when the recorded dimension contradicts the stored data, and `o2b search restamp` repairs the one drift that needs no provider. Every structured Brain record carries a server-derived `origin_channel` no caller can supply; Brain status derives `log_events_since_dream` from the shards it already reads and names an unreadable shard a lower bound; imports read back what they claim and report every missing key by name, and the sessions lane resumes an interrupted transcript at the turn boundary; the three note-producing envelope lanes hand the generating agent a bounded, ownership-filtered wikilink candidate manifest; a failed multi-artifact write leaves a durable dead letter; and a standing census documents - truthfully - that `visibility: private` is a view filter, not a privacy boundary, with `o2b search check` saying so on vaults that use the field.
+The reach that decides is a transport fact, not a request field. stdio and the command line mint `local`, because the caller already started the process and holds whatever filesystem access it runs with; every non-loopback HTTP bind mints `remote`. A caller that puts a reach-shaped argument in a tool call is refused by name rather than quietly ignored, and what the local bypass actually proves is written down where it is defined rather than overclaimed. A withheld page is reported exactly as an absent one - byte for byte on the key-addressed reads, where the key spaces are enumerable and a distinguishable refusal would be an existence oracle over the population being hidden. Twenty-four of the seventy-six enumerated note-returning surfaces now consult the field, up from three of seventy-one, and `o2b search check` reports the honest remainder alongside the count of pages the boundary withholds. Schema 12 records what the index measured of each page's frontmatter and backfills it from data the index already holds, so a vault that never wrote the token sees no change at all and no operator has to reindex to get there.
+
+Previous releases, 1.53.1 and 1.53.0, closed a dedup pass that proposed the same merge forever and could write a merge cycle, and taught Hermes recall to carry the turn's query without leaving the curated lane that makes injection safe. The [CHANGELOG](CHANGELOG.md) has the detail on both.
+
+Previous release, 1.52.0, was the honesty wave: nothing writes silently, nothing degrades silently. Nine tracker cards were read against the live source before anything was designed, and the reading did most of the work - one card described a feature that had already shipped end to end, one asked for privacy by riding a predicate that is inert in every default install, and four more had premises the source contradicted. What survived is one rule applied eight ways.
+
+A note update now refuses to destroy what it could not read - an unreadable note raises `target_unreadable` instead of parsing as empty, and a blank body over a non-empty note needs an explicit `allow_empty`. `o2b search check` measures instead of inferring: a real pending-vector count replaces a recommendation that told fully embedded vaults to compute their first vectors, an embedder record audit reports when the recorded dimension contradicts the stored data, and `o2b search restamp` repairs the one drift that needs no provider. Every structured Brain record carries a server-derived `origin_channel` no caller can supply; Brain status derives `log_events_since_dream` from the shards it already reads and names an unreadable shard a lower bound; imports read back what they claim and report every missing key by name, and the sessions lane resumes an interrupted transcript at the turn boundary; the three note-producing envelope lanes hand the generating agent a bounded, ownership-filtered wikilink candidate manifest; a failed multi-artifact write leaves a durable dead letter; and a standing census documented - truthfully, at the time - that `visibility: private` was a view filter rather than a privacy boundary, with `o2b search check` saying so on vaults that use the field. That census is the coverage map 1.54.0 built the enforcement against.
The units speak one vocabulary on purpose: attempted, found, and missing with every missing key named, one pure module consumed by the import census, the write accounting, and the embedder audit, pinned by the same census that guards the project's other closed vocabularies. An independent reviewer given the finished branch returned two blocking findings and eleven non-blocking ones, all applied; the [CHANGELOG](CHANGELOG.md) names each.
diff --git a/docs/brainstorm/private-is-not-a-suggestion/cli-output/claude.md b/docs/brainstorm/private-is-not-a-suggestion/cli-output/claude.md
new file mode 100644
index 00000000..e6e8df5b
--- /dev/null
+++ b/docs/brainstorm/private-is-not-a-suggestion/cli-output/claude.md
@@ -0,0 +1,38 @@
+### Variant 1: Capability-scoped read primitives (choke point in core)
+
+- **Approach**: Move enforcement into the note-content-returning primitives themselves (`listVaultPages`, the read-page-by-path primitive, and the index query layer), which become deny-by-default: they consult a single `vaultPageVisible(metadata, disclosure)` predicate (built on the existing `visibility.ts` tokens, sibling in shape to `vaultPageInStatusScope`) before yielding a page. A server-side `disclosure` value is minted only by transport constructors β€” `serveStdio`, `startHttp` (loopback vs. non-loopback via `isLoopbackHost`), and `src/cli/main.ts` β€” and threaded into `ServerContext` and down through the primitives; no caller-supplied string can produce it. `applyVisibilityScope` is subsumed: the pool-filter call site delegates to the same predicate, so one rule has one spelling.
+- **Trade-offs**:
+ - Pro: new surfaces are safe by construction β€” a tool that imports the primitives cannot forget the filter, so the census's "excluded" category structurally empties.
+ - Pro: no existence oracle for free β€” a withheld page is literally never yielded, so counts, aggregates, and `_meta` cannot mention it.
+ - Con: signature churn β€” `disclosure` must thread from three transports through `ServerContext` into core primitives, touching most of the 17 `listVaultPages` call sites plus every tool that constructs core calls; the wave lands at the top of the 50–70 file budget.
+ - Con: internal engine lanes (indexer, dedup pool, link-graph repair) legitimately need unfiltered reads; they need a named in-process full-disclosure value, and drawing that line wrong either breaks wikilink integrity or quietly re-opens the hole.
+ - Con: honest bypass statement is weak-but-defensible: stdio/CLI/loopback prove only "the caller already has filesystem-equivalent access to this vault," not operator intent.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Per-surface predicate sweep, census-enforced
+
+- **Approach**: Define the same single predicate once, but leave primitives unfiltered and sweep all 68 `excluded` surfaces (including `src/openclaw/index.ts:128`) to adopt it at their own enumeration/read points, exactly as `vaultPageInStatusScope` was adopted. Each adoption flips its registry row from `excluded` to `covered` with a written reason; the agent-scope matrix gains a seeded `visibility:` corpus axis (including `_meta` and a federated caller shape), so an unclassified or wrongly-wired surface fails the suite.
+- **Trade-offs**:
+ - Pro: maximally reviewable β€” 68 small, independent, idiom-matching diffs; the registry and honesty finding move row by row, making progress and closure legible.
+ - Pro: no plumbing churn; transports still mint the `disclosure` server-side, but it only has to reach tool handlers, not core signatures.
+ - Con: enforcement stays distributed forever β€” every future surface is one forgotten predicate away from a leak, and only the census/matrix (not the type system or call graph) stands between it and shipping.
+ - Con: no-existence-oracle must be re-proven per surface (backlink counts, graph aggregates, thrown messages), which is exactly the class of error a 68-site sweep invites.
+ - Con: heaviest test burden: the matrix must drive every surface against the visibility corpus in both directions to make the claim real.
+- **Complexity**: large
+- **Risk**: medium-high
+
+### Variant 3: Two-root enforcement with a fail-closed index column
+
+- **Approach**: Observe that every callable surface reaches page content through one of three roots β€” `listVaultPages`, the read-by-path primitive, or the search index β€” and enforce only there, with the census extended to prove no fourth root exists (mechanical sweep for direct `fs` reads of vault paths under `src/mcp/`, `src/cli/`, `src/openclaw/`). The index gains a per-document visibility column written at index time; query-side filtering treats a missing/unreadable value as private (fail closed), which makes the pre-existing-tagged-page population self-healing β€” stale fastpath-skipped rows have no column, so they are withheld immediately and correctly reclassified on the next content read, with a one-time persisted store marker (not `indexRevision`, which is only a cache generation) forcing full frontmatter re-examination once. Private pages stay indexed but flagged, so the transport-keyed `disclosure` can lift the filter for local callers without a segregated store; the indexer skip-vs-delete trap (`seen.add` at `indexer.ts:390`) never arises because nothing is skipped.
+- **Trade-offs**:
+ - Pro: smallest enforcement surface β€” three choke points plus a census that proves their sufficiency; the 68 registry rows flip to `covered` by root, each citing which root covers it.
+ - Pro: index handling is the cleanest of the three: fail-closed column solves the mtime-fastpath legacy population without a purge/migration dance, and trusted-local search over private pages keeps working.
+ - Con: private page bodies remain in `chunks`/`chunk_fts` at rest β€” anyone with file access to the store reads them; this must be stated plainly (it is the same trust boundary as the vault files themselves, but it is a fact, not nothing).
+ - Con: the whole guarantee hangs on the root-closure census being right; a surface that shells out or re-implements a walk escapes until the census learns that shape.
+ - Con: read-by-path root must refuse with the same `not found` an absent page produces, and that message-identity must be asserted in the matrix.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Recommended: Variant 3
+**Rationale**: Variant 3 delivers Variant 1's safe-by-construction property at a fraction of the signature churn, fits comfortably inside the 50–70 file wave, and is the only variant whose index-side story respects all four verified indexer facts without a fragile purge path β€” the fail-closed column turns the pre-existing-private-page obligation from a migration into a default. It subsumes `applyVisibilityScope` naturally (the search root is one of the three choke points), and its residual risk β€” trusting the root-closure census β€” is exactly the mechanism this project has already chosen and shipped for population claims, so extending the census to prove "no fourth root" is idiomatic rather than novel.
diff --git a/docs/brainstorm/private-is-not-a-suggestion/cli-output/prompt.md b/docs/brainstorm/private-is-not-a-suggestion/cli-output/prompt.md
new file mode 100644
index 00000000..d0bd59bd
--- /dev/null
+++ b/docs/brainstorm/private-is-not-a-suggestion/cli-output/prompt.md
@@ -0,0 +1,131 @@
+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
+
+Make `visibility:` frontmatter a real enforcement boundary in Open Second Brain, instead of a caller-liftable filter wired into one search lane.
+
+Two kanban cards back this scope. BOTH have had premises refuted against live source; the refutations are stated here as findings, not as work to redo.
+
+## Card t_92c26f69 - "Per-page visibility:private flag riding on the existing owner-scope predicate"
+
+Original claim: "No `visibility`/`private` frontmatter handling in the read surfaces; extend `gatedOwnerScopeView` to also honour a per-page `visibility: private` flag."
+
+REFUTED, verified this run:
+ - `src/core/graph/visibility.ts` already ships `pageVisibility()` (line 31), `normalizeVisibilityScope()` (38) and `isVisible()` (53) over opaque, language-neutral tokens.
+ - `src/core/search/result-filters.ts:249` `applyVisibilityScope` applies them.
+ - It is wired at exactly ONE call site: `src/core/search/pipeline/pool-filters.ts:130`, inside `search()`.
+ - `gatedOwnerScopeView` (`src/core/brain/owner-scope-view.ts`) is the WRONG carrier: its own docblock states `scope === null` short-circuits every predicate to `true` unless the operator has set `integrity.owner_scope_delivery: fail`, and that `warn` is inert on every surface that uses this view. It gates Brain ARTIFACTS by path, not vault pages by frontmatter. Riding it would ship privacy that is off by default.
+
+REMAINING ASK: one deny-by-default predicate honouring a reserved private token, independent of owner-scope config, with a trusted-local bypass keyed on TRANSPORT and never on a caller-supplied string.
+
+## Card t_8f670d8e - "Registry-driven remote privacy sweep across every MCP operation"
+
+Original claim: "no registry-driven harness that sweeps every remote operation against a private corpus, and no fail-closed unclassified-newcomer gate."
+
+REFUTED, verified this run:
+ - `tests/mcp/agent-scope-matrix.test.ts` partitions the entire live `buildToolTable("full")` table into buckets in BOTH directions, drives every entry against a two-owner fixture, and asserts neither the response nor the thrown message carries a marker unique to the other owner. A new or removed tool fails the suite until classified.
+ - `tests/core/architecture/visibility-surface-census.test.ts` mechanically sweeps `src/mcp/` for files importing note-content-returning primitives, resolves tool names through constants, cross-checks against the live tool table, and pins the population as an equality (43 MCP tools, 8 resources, 20 CLI verbs).
+
+REMAINING ASK, three named gaps:
+ 1. The matrix's axis is OWNER, not VISIBILITY. Its fixture is a two-owner vault; no seeded `visibility:`-tagged corpus.
+ 2. No assertion on the MCP `_meta` channel (`src/mcp/progress.ts` shows `_meta` is a live response member).
+ 3. No federated / multi-source caller shape in the matrix.
+ 4. `tests/core/architecture/visibility-surface-census.test.ts:84-86` names `src/openclaw/index.ts` as an un-swept page-search surface, out of that census's charter. Verified: `src/openclaw/index.ts:128` calls `listVaultPages(vault)` and filters only by entity status scope (`vaultPageInStatusScope`), never by visibility.
+
+# Measured starting state (read off the live registry this run, not estimated)
+
+ - `src/core/search/visibility-surface-registry.ts` holds 72 rows: 71 callable + 1 `index_store` structural row.
+ - 68 of 71 callable surfaces are category `excluded` - they can return a page's path, title or body without ever consulting `visibility:`.
+ - Exactly 3 are `covered`: `brain_search`, `brain_file_context`, and the CLI verb `search query`. All three are covered only because they route through `search()`.
+ - `src/core/search/indexer.ts` chunks every page regardless of its tag; the registry's `index_store` row states this in its own words ("stored in chunks and mirrored into chunk_fts regardless of any read-side filter").
+ - `o2b search check` emits a visibility honesty finding (`src/core/search/indexer.ts:1672`) whose counts are read off `excludedCallableVisibilitySurfaces()` at call time, so the finding recounts itself as surfaces move category.
+
+# Index-side facts that a variant must respect (verified, and they correct a widely-repeated assumption)
+
+ - `indexRevision` (`src/core/search/store/state.ts:112-118`) is a MONOTONIC QUERY-CACHE GENERATION COUNTER bumped after any mutating index run, consumed by `computeCorpusGeneration` (`src/core/search/corpus-generation.ts:32`). It is NOT a schema or index-format revision. Bumping it invalidates cached query results; it does NOT force a reindex. Any variant that claims "this forces a full reindex for every vault" is wrong about this mechanism.
+ - The indexer's deletion sweep (`src/core/search/indexer.ts:537-540`) removes any stored document the walk did not yield. So a page that STOPS being yielded has its chunks purged on the next ordinary incremental run.
+ - BUT `seen.add(file.relPath)` happens at `indexer.ts:390`, BEFORE the content read and frontmatter parse. A "skip private pages" that merely `continue`s after parsing frontmatter leaves the path marked seen and its stale chunks in place. Exclusion has to route into an explicit delete, or the skip has to happen before the mark.
+ - `walkVault` (`src/core/search/walker.ts`) does not parse frontmatter at all - it yields `.md` files by scope rules and `statSync`. A visibility decision needs frontmatter, which only the indexer body reads.
+ - The mtime+size fastpath (`indexer.ts:400`) skips the content read entirely when both match. A page that was ALREADY tagged private before this feature ships has an unchanged mtime, so an ordinary incremental run never re-examines it and its chunks survive. Handling that pre-existing population is a real, nameable design obligation.
+
+# Transport facts (for the trusted-local bypass)
+
+ - `ServerContext` (`src/mcp/tool-contract.ts:101-128`) carries `vault`, `configPath`, `repoRoot`, `capabilityReport`, `artifactStore`, `agentName`. There is NO transport field today.
+ - Two transports construct the server: `serveStdio` (`src/mcp/stdio.ts:65`) and `startHttp` / `serveHttp` (`src/mcp/http.ts:61`, `:198`). `isLoopbackHost` (`src/mcp/http.ts:338`) already exists, and `startHttp` already refuses a non-loopback bind without an API key.
+ - `MCPServer.context` (`src/mcp/server.ts:152`) is a GETTER that rebuilds the context per access.
+ - The CLI (`src/cli/main.ts`) also invokes tool handlers directly (`o2b tool-call`), which is a third caller shape.
+ - Note the honest difficulty: stdio is not automatically "trusted". A remote host can spawn a stdio subprocess. State clearly what your variant's bypass actually proves.
+
+# Existing idiom to imitate rather than reinvent
+
+ - `src/core/brain/entities/page-scope.ts` - `vaultPageInStatusScope(metadata, scope)`: a page-level predicate over the frontmatter a walker already parsed, defined once, adopted by `src/openclaw/index.ts` and `src/core/brain/link-graph/repair-lane.ts`. This is the closest existing shape to what a visibility predicate should look like.
+ - `src/mcp/owner-scope-refusal.ts` - the project's stated rule that an identity echoed back from the request is not an identity; a disagreement is refused BY NAME rather than silently substituted.
+ - `src/mcp/resources.ts` `gatedOwnerScopeView` usage - a withheld artifact is reported with the same `not found` message an absent one produces, so a refusal does not announce the page it hides (no existence oracle).
+
+# Project context
+
+Open Second Brain. TypeScript on Bun. Monolithic repo; `src/core/` is the engine, `src/mcp/` the MCP server, `src/cli/` the CLI, `src/openclaw/` a native plugin adapter, `plugins/hermes/` a Python sidecar. Tests under `tests/` run with `bun test`.
+
+Recent commits:
+23e6b81e fix(brain): merged pages leave the dedup pool, and the write seam refuses cycles (v1.53.1) (#182)
+c2e13f9d fix(hermes): make prefetch recall query-aware (#181)
+5102f142 fix(hermes): record context-pack receipts and explicit outcomes (#179)
+323e2f09 feat: nothing writes silently, nothing degrades silently (v1.52.0) (#178)
+6d3e8b23 feat: what earns its keep (v1.51.0) (#177)
+b49af81e feat: a label is not a boundary (v1.49.0) (#166)
+
+Related files:
+src/core/graph/visibility.ts
+src/core/search/result-filters.ts
+src/core/search/pipeline/pool-filters.ts
+src/core/search/visibility-surface-registry.ts
+src/core/search/indexer.ts
+src/core/search/walker.ts
+src/core/vault.ts (listVaultPages, 17 call sites)
+src/openclaw/index.ts
+src/mcp/tool-contract.ts
+src/mcp/server.ts
+src/mcp/stdio.ts
+src/mcp/http.ts
+src/mcp/owner-scope-refusal.ts
+src/core/brain/owner-scope-view.ts
+src/core/brain/entities/page-scope.ts
+tests/mcp/agent-scope-matrix.test.ts
+tests/core/architecture/visibility-surface-census.test.ts
+
+Conventions, taken from the repository's own shipped code and its agent guidance:
+- SOLID, KISS, DRY. Repeated literals hoist into named constants. One rule, one spelling: a second spelling of the same rule is treated as a defect.
+- No silent fallback. A degradation is named and surfaced, never quietly absorbed. "Nothing writes silently, nothing degrades silently" is a shipped release title in this repo.
+- No stubs, no placeholder values, no hardcoded natural-language phrases in any language. Visibility tokens are opaque and language-neutral by existing design; nothing may enumerate the languages of the world or hardcode a closed natural-language enum.
+- Fail closed on unreadable state: an ownership or visibility claim that cannot be read is not an absence of one.
+- No existence oracle: a withheld page must be indistinguishable from an absent one, including in counts, aggregates and error messages.
+- Census and matrix tests are the project's chosen mechanism: a population is pinned as an equality, a newcomer fails the suite until classified, and a reason is written per entry.
+- Every artifact is English.
+
+Constraints:
+- Deny by default. A variant whose protection is off unless an operator sets a config key does not meet the ask.
+- The trusted-local bypass must key on transport or another server-side fact, never on a caller-supplied string.
+- Zero behaviour change for vaults that never set `visibility:`. Default-visibility pages must stay reachable everywhere, and the cost for such a vault must be near zero.
+- This is a BEHAVIOUR CHANGE for vaults that do set it: pages that read today over MCP stop reading. Say how your variant makes that legible to the operator.
+- Do not introduce a second enforcement path alongside `applyVisibilityScope`; either subsume it or state plainly why two exist.
+- No new external dependencies.
+- The wave is sized at roughly 50-70 changed files. A variant that cannot be reviewed at that size should say so.
+- `src/openclaw/index.ts` is in scope: it is the un-swept page walker the census names.
+- The existing registry and matrix must be able to PROVE the closure, not merely describe it - the covered/excluded counts must move and the honesty finding must recount itself.
+
+# 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/private-is-not-a-suggestion/design.md b/docs/brainstorm/private-is-not-a-suggestion/design.md
new file mode 100644
index 00000000..51a080bf
--- /dev/null
+++ b/docs/brainstorm/private-is-not-a-suggestion/design.md
@@ -0,0 +1,284 @@
+# Private is not a suggestion - `visibility:` becomes an enforcement boundary
+
+**Status:** draft
+**Author:** claude-dev-agent (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+Open Second Brain ships a `visibility:` frontmatter field, a predicate that
+reads it, and a filter that applies it - and the filter is wired into exactly
+one call site. Of the 71 callable surfaces the project's own visibility
+registry enumerates, 68 can hand back a page's path, title or body without
+ever consulting the field. The three that do consult it (`brain_search`,
+`brain_file_context`, the CLI verb `search query`) do so through a caller
+argument, so a remote caller that asks for the private scope is given it. A
+page's tag is therefore decorative everywhere and liftable where it is not.
+
+The previous wave (v1.52.0) measured this rather than fixing it: it shipped
+the surface census, the registry that backs it, and a `search check` honesty
+finding that states in the operator's own diagnostics that this boundary does
+not exist. This wave is the enforcement that census was built as the coverage
+map for.
+
+## Premise verification
+
+Both source cards had premises refuted against live source before any design
+work. The verdicts are deliverables in their own right and are recorded here
+rather than silently built around.
+
+### t_92c26f69 - REFUTED on both claims, rescoped
+
+| Card claim | Verdict | Evidence |
+|---|---|---|
+| "No `visibility`/`private` frontmatter handling in the read surfaces" | **Refuted** | `src/core/graph/visibility.ts` ships `pageVisibility` (:31), `normalizeVisibilityScope` (:38), `isVisible` (:53); `src/core/search/result-filters.ts:249` applies them |
+| "Extend `gatedOwnerScopeView` to also honour a per-page `visibility: private` flag" | **Refuted as an approach** | `src/core/brain/owner-scope-view.ts`'s own docblock states `scope === null` short-circuits every predicate to `true`, and that `warn` is inert on every surface using the view. It is reached only under `integrity.owner_scope_delivery: fail`, and it gates Brain artifacts by path rather than vault pages by frontmatter. Riding it would ship privacy that is off by default |
+
+Rescoped ask, which is what this wave builds: one deny-by-default predicate
+honouring a reserved token, independent of owner-scope configuration, with a
+bypass keyed on a server-side transport fact rather than on anything the
+caller says.
+
+### t_8f670d8e - REFUTED on its central claim, rescoped to three named gaps
+
+| Card claim | Verdict | Evidence |
+|---|---|---|
+| "No registry-driven harness that sweeps every remote operation against a private corpus" | **Refuted** | `tests/mcp/agent-scope-matrix.test.ts` partitions the live `buildToolTable("full")` in both directions and drives every entry against a seeded fixture |
+| "No fail-closed 'unclassified new operation breaks the suite' gate" | **Refuted** | Both the matrix and `tests/core/architecture/visibility-surface-census.test.ts` fail on an unclassified newcomer; the census pins its population as an equality (43 MCP tools, 8 resources, 20 CLI verbs) |
+
+What survives: the existing harness's axis is OWNER, not VISIBILITY. Its
+fixture is a two-owner vault with no `visibility:`-tagged corpus; it asserts
+nothing about the MCP `_meta` response member; it drives no federated caller
+shape. Plus one follow-up the card did not carry:
+`tests/core/architecture/visibility-surface-census.test.ts:84-88` names
+`src/openclaw/index.ts` as an un-swept page-search surface, and
+`src/openclaw/index.ts:128` does call `listVaultPages(vault)` filtered only by
+entity status scope.
+
+### Correction to the wave's own stated risk
+
+The scope brief for this wave asserted that the work "moves `indexRevision`",
+forcing a reindex for every vault, and must therefore be scheduled apart from
+index-health releases. That is wrong about the mechanism.
+`src/core/search/store/state.ts:112-118` defines `indexRevision` as a
+monotonic counter bumped after any mutating index run, consumed only by
+`computeCorpusGeneration` (`src/core/search/corpus-generation.ts:32`) to
+invalidate the query cache. It is not a schema or index-format revision and
+bumping it forces nothing. The real index-side obligations are different and
+are stated under "Design decisions" below.
+
+## Scope
+
+- One deny-by-default predicate, `isRemotelyReadable`, in
+ `src/core/graph/visibility.ts`, honouring a reserved visibility token that
+ means "not readable at reduced disclosure".
+- A closed disclosure vocabulary minted server-side by each transport and
+ carried on `ServerContext`; a caller-supplied disclosure is refused by name.
+- Enforcement at the three roots every callable surface reaches page content
+ through: the search pipeline, `listVaultPages`, and the by-path/by-chunk-id
+ read primitives.
+- `applyVisibilityScope` subsumed by the new predicate, so the rule has one
+ spelling.
+- `src/openclaw/index.ts`'s page walker brought under the boundary and into
+ the census population.
+- A `documents.visibility` column written by the indexer, with a schema
+ migration that backfills every pre-existing row from the frontmatter the
+ index already stores.
+- Registry reclassification: rows move `excluded` to `covered` naming which
+ root covers them, and the `search check` honesty finding recounts itself off
+ the registry as it already does.
+- Census extended to prove root closure - that no fourth root exists.
+- The agent-scope matrix gains a visibility axis, an `_meta` envelope
+ assertion, and a federated caller shape.
+
+## Out of scope
+
+- Encryption at rest. A private page's body remains in `chunks` and
+ `chunk_fts`; anyone with file access to `brain.sqlite` reads it. This is the
+ same trust boundary as the vault's own Markdown files, and the registry's
+ `index_store` row already states it. This wave keeps that row and updates its
+ wording; it does not close it.
+- Owner-scope delivery. `integrity.owner_scope_delivery` and this boundary are
+ independent rules over different subjects, and neither is folded into the
+ other.
+- Any new operator configuration key. Deny-by-default means the boundary is
+ not something an operator has to switch on.
+- Per-token access-control policy (who may see `team`, `agent:foo`, and so
+ on). Non-reserved tokens keep exactly today's caller-liftable scoping
+ semantics.
+
+## Chosen approach
+
+Three roots, one predicate, an index column that is measured rather than
+assumed.
+
+Every surface in the registry reaches a page's path, title or body through one
+of three roots: `search()`'s pipeline, `listVaultPages`, or a read primitive
+that takes a path or a chunk id. Enforcement goes at those three roots and
+nowhere else, and the census is extended to prove there is no fourth. This is
+the shape the project already uses for status scoping
+(`src/core/brain/entities/page-scope.ts`: one predicate over frontmatter a
+walker has already parsed, adopted by its callers rather than reimplemented).
+
+The predicate takes a *disclosure* rather than a caller-supplied scope. A
+disclosure is a value from a closed vocabulary that only a transport
+constructor can mint: `serveStdio`, `startHttp` (which already distinguishes
+loopback from network via `isLoopbackHost` and already refuses an
+unauthenticated non-loopback bind), and the CLI's direct handler invocation.
+A caller that puts a disclosure-shaped value in its arguments is refused by
+name, following the rule `src/mcp/owner-scope-refusal.ts` states once: an
+identity echoed back from the request is not an identity.
+
+At reduced disclosure a page carrying the reserved token is not returned, not
+counted, and not named in an error - a withheld page is reported exactly as an
+absent one, the convention `src/mcp/resources.ts` already holds for
+owner-scope. The caller's existing `visibility` argument keeps working and can
+only ever NARROW: it can no longer lift the reserved token.
+
+## Design decisions
+
+- **Deny by default, no config key.** A boundary an operator must enable is
+ the defect the previous wave's honesty finding named. There is no opt-out
+ key in this design; the escape hatch is the transport a caller arrives on,
+ which the operator already controls when they choose how to expose the
+ server.
+
+- **The reserved token is a named constant, not a phrase.** Visibility tokens
+ stay opaque and language-neutral, exactly as `graph/visibility.ts` already
+ documents. One token is reserved as a vocabulary identifier - the same kind
+ of thing as `kind: entity` or an entity `status` value, both of which this
+ repository already treats as identifiers rather than prose. It is hoisted
+ into a single exported constant, and every other token keeps today's
+ semantics untouched.
+
+- **Disclosure is minted, never parsed.** It is keyed on the transport, not on
+ a string in the request, because a caller-supplied trust claim is not a
+ trust claim. What the bypass actually proves is stated plainly rather than
+ overclaimed: stdio and the CLI prove the caller already holds
+ filesystem-equivalent access to this vault, and loopback HTTP proves the
+ request originated on this host. Neither proves operator intent, and the
+ design says so where it is implemented.
+
+- **The index column is backfilled from data the index already holds.** The
+ consultant's recommended variant proposed treating a missing column value as
+ private, calling the legacy population "self-healing". Verified against
+ source, that is a total search blackout: `applyMigrations`
+ (`src/core/search/schema.ts:773`) adds a column with NULL for every existing
+ row, so on upgrade every document in every vault - including the
+ overwhelming majority that have never used `visibility:` at all - would be
+ withheld until a full reindex. That breaks the wave's own zero-behaviour-
+ change constraint. The correction: the migration backfills. `packBlocks`
+ (`src/core/search/chunker.ts:312-330`) emits a page's frontmatter as its own
+ chunk, whole and without overlap, at `chunk_index = 0` - a structural fact
+ `src/core/search/store/visibility-tag.ts` already depends on and
+ `tests/core/search/visibility-tag-presence.test.ts` already pins. The
+ migration therefore parses the stored frontmatter for every existing
+ document and writes the column with no vault walk and no operator action.
+
+- **Unmeasured is a third state and is denied.** A page whose frontmatter the
+ index cannot produce - an unterminated frontmatter block, which
+ `chunker.ts:137-141` omits, or a document with no chunks - is not measurable
+ from the index. It is left NULL, and NULL is withheld at reduced disclosure.
+ Fail closed: a visibility claim that cannot be read is not the absence of
+ one, the convention `owner-scope-view.ts` states for ownership. The count of
+ such rows is reported by `search check` rather than absorbed.
+
+- **Private pages stay indexed.** Excluding them from the index would take an
+ operator's own private notes out of their own local search, which is a
+ product regression dressed as a hardening. They are indexed and marked, so
+ the search root filters in SQL on the column instead of re-reading
+ frontmatter per candidate, and a caller holding a raw chunk id is gated by
+ the same column.
+
+- **The indexer marks; it does not skip.** A "skip private pages" written as a
+ `continue` after the frontmatter parse would be a live defect:
+ `indexer.ts:390` adds the path to `seen` BEFORE the content is read, so the
+ deletion sweep at `indexer.ts:537-540` would not purge the stale rows and
+ the page would keep whatever chunks it already had. Writing the column on
+ every upsert avoids the trap entirely, which is the second reason to mark
+ rather than exclude.
+
+- **One spelling of the rule.** `applyVisibilityScope` is not left beside the
+ new predicate; it is reimplemented on top of it. Two functions answering
+ "may this caller see this page" is the defect
+ `src/mcp/owner-scope-refusal.ts` was written to remove on the ownership
+ side.
+
+- **The proof is the existing instruments, moved.** The registry rows change
+ category with a written reason each; `excludedCallableVisibilitySurfaces()`
+ is already what the honesty finding counts (`indexer.ts:1672`), so the
+ operator-facing number falls on its own. No new count is hand-written.
+
+## File changes
+
+New:
+
+- `src/core/graph/disclosure.ts` - the closed disclosure vocabulary and its
+ narrowing predicate.
+- `tests/core/graph/remote-readability.test.ts` - the predicate's truth table.
+- `tests/core/search/visibility-column-backfill.test.ts` - the migration over
+ a pre-boundary index.
+- `tests/mcp/disclosure-refusal.test.ts` - a caller-supplied disclosure is
+ refused by name.
+- `tests/mcp/visibility-matrix.test.ts` - the visibility axis, `_meta`
+ assertion and federated caller shape, if it does not fit inside the existing
+ matrix file.
+- `tests/core/architecture/read-root-closure.test.ts` - the no-fourth-root
+ sweep, if it does not fit inside the existing census file.
+
+Modified (principal):
+
+- `src/core/graph/visibility.ts` - `isRemotelyReadable`, the reserved-token
+ constant, and `isVisible` retained as the narrowing half.
+- `src/core/search/result-filters.ts` - `applyVisibilityScope` reimplemented
+ on the predicate.
+- `src/core/search/pipeline/pool-filters.ts` - disclosure carried into the
+ filter; the caller argument narrows only.
+- `src/core/vault.ts` - `listVaultPages` takes a disclosure and enforces it.
+- `src/openclaw/index.ts` - the page walker adopts it.
+- `src/core/search/schema.ts` - migration 12, column plus backfill.
+- `src/core/search/store/documents.ts` - the column on read and write.
+- `src/core/search/indexer.ts` - writes the column on upsert; `search check`
+ reports the unmeasured count.
+- `src/core/search/visibility-surface-registry.ts` - reclassification.
+- `src/mcp/tool-contract.ts`, `src/mcp/server.ts`, `src/mcp/stdio.ts`,
+ `src/mcp/http.ts`, `src/cli/main.ts` - minting and threading the disclosure.
+- `tests/core/architecture/visibility-surface-census.test.ts` - population
+ pins move; `src/openclaw/` enters the sweep.
+- `tests/mcp/agent-scope-matrix.test.ts` - visibility axis.
+- The remaining `listVaultPages` call sites in `src/core/brain/**` - each
+ passes the named full-disclosure value, because an internal maintenance lane
+ that stopped seeing private pages would corrupt the link graph it repairs.
+- `README.md`, `CHANGELOG.md`, `package.json` and the mirrored version
+ manifests via `scripts/sync-version.ts`.
+
+## Risks and open questions
+
+- **Behaviour change for vaults that do tag pages.** Pages that read over MCP
+ today stop reading. This is the point of the wave, but it has to be legible:
+ `search check` must report the count of pages the boundary now withholds,
+ and the release notes must lead with it. Vaults that never set `visibility:`
+ see no change at all, and the migration is what guarantees that rather than
+ an assumption.
+- **The bypass proves less than it sounds like it proves.** A remote host can
+ spawn a stdio subprocess. Stated at the implementation site and in the
+ release notes rather than papered over; the alternative - no bypass at all -
+ would take an operator's private notes away from their own CLI.
+- **Root closure is the whole guarantee.** A surface that reads a vault file
+ directly rather than through one of the three roots escapes until the census
+ learns that shape. The sweep for direct filesystem reads of vault paths
+ under `src/mcp/`, `src/cli/` and `src/openclaw/` is what makes the claim
+ checkable, and its blind spots are written down the way the existing
+ census's are.
+- **Open question, resolved during implementation:** whether the backfill runs
+ inside migration 12's transaction or as a post-migration pass. The parse is
+ over every document's chunk-zero row, which on a large vault is the cost of
+ one table scan; if that proves unacceptable inside the migration
+ transaction, it moves to a post-open pass with the same fail-closed NULL
+ semantics in the meantime. The decision is measured, not guessed, and the
+ measurement is part of Task 6.
+- **Open question, resolved during implementation:** whether the visibility
+ matrix axis fits inside `tests/mcp/agent-scope-matrix.test.ts` or needs a
+ sibling file. The existing file is already large; the deciding factor is
+ whether the two axes can share one fixture without either one's assertions
+ becoming conditional.
diff --git a/docs/brainstorm/private-is-not-a-suggestion/plan.md b/docs/brainstorm/private-is-not-a-suggestion/plan.md
new file mode 100644
index 00000000..8acea55d
--- /dev/null
+++ b/docs/brainstorm/private-is-not-a-suggestion/plan.md
@@ -0,0 +1,192 @@
+# Private is not a suggestion - implementation plan
+
+Nine atomic units, each a separate conventional commit on
+`feat/private-is-not-a-suggestion`. Every unit is test-first: the acceptance
+line names a test that must fail with the stated error before the
+implementation exists. Formatter and linter run green before every commit.
+
+Tasks 1 and 2 are the kernel and everything else depends on them. Tasks 3, 4
+and 5 are the three roots and are independent of each other. Task 6 is the
+index column. Tasks 7, 8 and 9 are the proof, and each needs the roots it
+measures to be in place.
+
+## Tasks
+
+### Task 1: The predicate and the reserved token
+
+- **Files**: `src/core/graph/visibility.ts`,
+ `tests/core/graph/remote-readability.test.ts`
+- **What**: add `REMOTE_DENY_VISIBILITY_TOKEN` as a single exported constant
+ and `isRemotelyReadable(pageTags, disclosure)` beside the existing
+ `pageVisibility` / `normalizeVisibilityScope` / `isVisible`. Deny by
+ default: a page carrying the reserved token is readable only at full
+ disclosure. Untagged pages and pages carrying only non-reserved tokens are
+ unaffected by this predicate and keep answering to `isVisible` alone.
+- **Acceptance**: `tests/core/graph/remote-readability.test.ts` pins the truth
+ table across the cross-product of {untagged, reserved token, non-reserved
+ token, reserved plus non-reserved} and {full, reduced} disclosure, including
+ that token matching is the same NFC + lower-case normalisation
+ `normToken` already performs, so a second spelling of the reserved token
+ does not exist. Fails before implementation with the symbol missing.
+- **Depends on**: none
+
+### Task 2: Disclosure is minted by the transport and refused from the caller
+
+- **Files**: `src/core/graph/disclosure.ts` (new), `src/mcp/tool-contract.ts`,
+ `src/mcp/server.ts`, `src/mcp/stdio.ts`, `src/mcp/http.ts`,
+ `src/cli/main.ts`, `tests/mcp/disclosure-refusal.test.ts` (new)
+- **What**: a frozen closed vocabulary with exactly two members and a
+ narrowing predicate, in the shape `ENTITY_STATUS_SCOPE` and
+ `VISIBILITY_SURFACE_CATEGORY` already use. `ServerContext` gains a required
+ `disclosure`. `serveStdio` and the CLI's direct handler invocation mint full
+ disclosure; `startHttp` mints full on a loopback bind and reduced otherwise,
+ reusing `isLoopbackHost`. A disclosure-shaped member in a tool's arguments
+ is refused by name, following `src/mcp/owner-scope-refusal.ts`'s stated
+ rule.
+- **Acceptance**: the new test asserts each transport's minted value, and
+ asserts that a request carrying the argument is refused with the reason
+ named in the message rather than silently ignored or silently honoured.
+ Fails before implementation because `ServerContext` has no such field.
+- **Depends on**: Task 1
+
+### Task 3: Root A - the search pipeline, and one spelling of the rule
+
+- **Files**: `src/core/search/result-filters.ts`,
+ `src/core/search/pipeline/pool-filters.ts`, `src/core/search/search.ts`,
+ `src/core/search/types.ts`, `tests/core/search/visibility-filter.test.ts`,
+ `tests/mcp/visibility-scope.test.ts`
+- **What**: `applyVisibilityScope` is reimplemented on `isRemotelyReadable`
+ rather than left beside it. The pipeline carries the request's disclosure;
+ the caller's `visibility` argument keeps narrowing and can no longer lift
+ the reserved token.
+- **Acceptance**: the existing `tests/mcp/visibility-scope.test.ts` fixture
+ already seeds a `visibility: [private]` page; a new case asserts that a
+ caller passing that scope at reduced disclosure gets nothing back, and that
+ the same call at full disclosure is unchanged from today. The existing
+ passing assertions stay green.
+- **Depends on**: Tasks 1, 2
+
+### Task 4: Root B - `listVaultPages`, and the OpenClaw walker
+
+- **Files**: `src/core/vault.ts`, `src/openclaw/index.ts`, the remaining
+ `listVaultPages` call sites under `src/core/brain/**`,
+ `tests/core/vault/list-vault-pages-visibility.test.ts` (new),
+ `tests/openclaw/page-search-visibility.test.ts` (new)
+- **What**: `listVaultPages` takes a disclosure and drops pages the predicate
+ denies, over the frontmatter it has already parsed - the shape
+ `vaultPageInStatusScope` established. Internal maintenance lanes (heal,
+ doctor, portability, link-graph repair, freshness, schema report) pass the
+ named full-disclosure value explicitly, because a repair lane that stopped
+ seeing private pages would corrupt the graph it repairs. `src/openclaw/`'s
+ page search - the surface the census names at
+ `visibility-surface-census.test.ts:84-88` - adopts the reduced value.
+- **Acceptance**: the new vault test asserts a tagged page is absent from a
+ reduced-disclosure listing and present at full; the OpenClaw test drives its
+ registered page-search handler against a seeded tagged vault and asserts the
+ page is missing from `pages` AND that `total_pages` does not count it, so
+ the aggregate is not an existence oracle. Both fail before implementation
+ because the parameter does not exist.
+- **Depends on**: Tasks 1, 2
+
+### Task 5: Root C - by-path and by-chunk-id reads answer as absent
+
+- **Files**: `src/mcp/resources.ts`, the read primitives the registry's
+ `excluded` rows name as path-keyed or chunk-id-keyed,
+ `tests/mcp/visibility-not-found-parity.test.ts` (new)
+- **What**: a withheld page is reported with the message an absent page
+ produces, byte for byte - the convention `src/mcp/resources.ts` already
+ holds for owner-scope, so a refusal does not announce what it hides.
+- **Acceptance**: the new test asserts message identity between a read of a
+ tagged page at reduced disclosure and a read of a path that does not exist,
+ for every path-keyed and chunk-id-keyed surface in scope. Fails before
+ implementation because the tagged read currently succeeds.
+- **Depends on**: Tasks 1, 2
+
+### Task 6: The `documents.visibility` column and its backfill
+
+- **Files**: `src/core/search/schema.ts`,
+ `src/core/search/store/documents.ts`, `src/core/search/store.ts`,
+ `src/core/search/indexer.ts`,
+ `tests/core/search/visibility-column-backfill.test.ts` (new)
+- **What**: schema migration 12 adds the column and backfills every existing
+ document by parsing the frontmatter the index already stores at
+ `chunk_index = 0` - the structural fact `store/visibility-tag.ts` depends on
+ and `visibility-tag-presence.test.ts` pins. The indexer writes the column on
+ every upsert. A row the index cannot measure - unterminated frontmatter, or
+ a document with no chunks - stays NULL and is withheld at reduced
+ disclosure. The search root filters on the column instead of re-reading
+ frontmatter per candidate.
+- **Acceptance**: the new test builds an index at schema 11 with one untagged
+ page, one tagged page and one page with unterminated frontmatter, migrates,
+ and asserts the three column states; a second case asserts that a vault
+ which never used `visibility:` returns byte-identical search results before
+ and after the migration, which is the zero-behaviour-change constraint made
+ executable. Fails before implementation with a missing-column SQL error.
+ This task also carries the measurement that answers the design's open
+ question about running the backfill inside the migration transaction.
+- **Depends on**: Task 1
+
+### Task 7: Root closure - the census proves there is no fourth root
+
+- **Files**: `tests/core/architecture/visibility-surface-census.test.ts`,
+ `src/core/search/visibility-surface-registry.ts`
+- **What**: extend the sweep to bring `src/openclaw/` into the population, and
+ add a mechanical check that no file under `src/mcp/`, `src/cli/` or
+ `src/openclaw/` reads a vault Markdown path through the filesystem directly
+ rather than through one of the three roots. Its blind spots are written down
+ the way the existing census's are, not implied.
+- **Acceptance**: the sweep's population pins move to their new measured
+ values and a synthetic intruder file performing a direct vault read is
+ reported. Fails before implementation because `src/openclaw/` is outside the
+ swept tree today.
+- **Depends on**: Tasks 3, 4, 5
+
+### Task 8: Reclassification, and the honesty finding recounts itself
+
+- **Files**: `src/core/search/visibility-surface-registry.ts`,
+ `src/core/search/indexer.ts`,
+ `tests/core/search/visibility-honesty-finding.test.ts`,
+ `tests/cli/search-check-visibility-honesty.test.ts`
+- **What**: every row that a root now covers moves from `excluded` to
+ `covered` with a written reason naming which root covers it. The
+ `index_store` row stays and is reworded: private bodies remain at rest in
+ `chunks`, and the column is what gates the read rather than the storage. The
+ `search check` finding gains the count of unmeasured documents, so the
+ legacy population is reported rather than absorbed.
+- **Acceptance**: the existing honesty tests keep deriving both counts from
+ `excludedCallableVisibilitySurfaces()` / `callableVisibilitySurfaces()` and
+ now assert the moved values; no count is hand-written anywhere. A new case
+ asserts the unmeasured count is present and derived from the store, not a
+ literal.
+- **Depends on**: Tasks 3, 4, 5, 6, 7
+
+### Task 9: The matrix gains a visibility axis, `_meta`, and a federated caller
+
+- **Files**: `tests/mcp/agent-scope-matrix.test.ts` (or a sibling
+ `tests/mcp/visibility-matrix.test.ts` if the two axes cannot share one
+ fixture)
+- **What**: the existing partition over the live tool table is driven a second
+ time against a seeded `visibility:`-tagged corpus at reduced disclosure. The
+ assertion covers the whole response envelope - structured fields, rendered
+ text, the thrown message, and the MCP `_meta` member `src/mcp/progress.ts`
+ shows is live - and is run in a federated multi-source caller shape as well
+ as the single-source one.
+- **Acceptance**: every entry in the tool table is driven against the tagged
+ corpus and asserted to carry no marker unique to the tagged page in any of
+ the four envelope channels, in both caller shapes. A newly added tool still
+ fails the suite until classified, in both directions, which the existing
+ partition assertions already enforce and which must stay green.
+- **Depends on**: Tasks 3, 4, 5, 6
+
+## Release-phase obligations, carried on this branch
+
+Per `CLAUDE.md`, which overrides the playbook's generic default, the version
+bump rides inside this pull request rather than following it:
+
+1. `CHANGELOG.md` entry under a new `## [X.Y.Z] - <date>` heading plus its
+ `[X.Y.Z]: .../compare/...` link reference at the foot of the file.
+2. `package.json` version bumped, then `bun run scripts/sync-version.ts`.
+3. `bun run scripts/sync-version.ts --check` green before the push.
+
+This is a behaviour change for vaults that tag pages, so the release is a
+minor bump, not a patch.
diff --git a/docs/brainstorm/private-is-not-a-suggestion/variants.md b/docs/brainstorm/private-is-not-a-suggestion/variants.md
new file mode 100644
index 00000000..476d4df2
--- /dev/null
+++ b/docs/brainstorm/private-is-not-a-suggestion/variants.md
@@ -0,0 +1,137 @@
+# Variants - private is not a suggestion
+
+The consultant run is reproduced verbatim below, followed by the
+orchestrator's decision. The primary consultant (Claude Code) returned three
+parseable variants and a recommendation on its first invocation, exit 0, so
+the fallback consultant was not run and `cli-output/codex.md` does not exist.
+
+The prompt the consultant received is `cli-output/prompt.md`. It carried the
+premise verifications already done against live source, so the consultant was
+reasoning about the real codebase rather than about the cards' refuted claims.
+
+---
+
+## Consultant output, verbatim
+
+### Variant 1: Capability-scoped read primitives (choke point in core)
+
+- **Approach**: Move enforcement into the note-content-returning primitives themselves (`listVaultPages`, the read-page-by-path primitive, and the index query layer), which become deny-by-default: they consult a single `vaultPageVisible(metadata, disclosure)` predicate (built on the existing `visibility.ts` tokens, sibling in shape to `vaultPageInStatusScope`) before yielding a page. A server-side `disclosure` value is minted only by transport constructors β€” `serveStdio`, `startHttp` (loopback vs. non-loopback via `isLoopbackHost`), and `src/cli/main.ts` β€” and threaded into `ServerContext` and down through the primitives; no caller-supplied string can produce it. `applyVisibilityScope` is subsumed: the pool-filter call site delegates to the same predicate, so one rule has one spelling.
+- **Trade-offs**:
+ - Pro: new surfaces are safe by construction β€” a tool that imports the primitives cannot forget the filter, so the census's "excluded" category structurally empties.
+ - Pro: no existence oracle for free β€” a withheld page is literally never yielded, so counts, aggregates, and `_meta` cannot mention it.
+ - Con: signature churn β€” `disclosure` must thread from three transports through `ServerContext` into core primitives, touching most of the 17 `listVaultPages` call sites plus every tool that constructs core calls; the wave lands at the top of the 50–70 file budget.
+ - Con: internal engine lanes (indexer, dedup pool, link-graph repair) legitimately need unfiltered reads; they need a named in-process full-disclosure value, and drawing that line wrong either breaks wikilink integrity or quietly re-opens the hole.
+ - Con: honest bypass statement is weak-but-defensible: stdio/CLI/loopback prove only "the caller already has filesystem-equivalent access to this vault," not operator intent.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Per-surface predicate sweep, census-enforced
+
+- **Approach**: Define the same single predicate once, but leave primitives unfiltered and sweep all 68 `excluded` surfaces (including `src/openclaw/index.ts:128`) to adopt it at their own enumeration/read points, exactly as `vaultPageInStatusScope` was adopted. Each adoption flips its registry row from `excluded` to `covered` with a written reason; the agent-scope matrix gains a seeded `visibility:` corpus axis (including `_meta` and a federated caller shape), so an unclassified or wrongly-wired surface fails the suite.
+- **Trade-offs**:
+ - Pro: maximally reviewable β€” 68 small, independent, idiom-matching diffs; the registry and honesty finding move row by row, making progress and closure legible.
+ - Pro: no plumbing churn; transports still mint the `disclosure` server-side, but it only has to reach tool handlers, not core signatures.
+ - Con: enforcement stays distributed forever β€” every future surface is one forgotten predicate away from a leak, and only the census/matrix (not the type system or call graph) stands between it and shipping.
+ - Con: no-existence-oracle must be re-proven per surface (backlink counts, graph aggregates, thrown messages), which is exactly the class of error a 68-site sweep invites.
+ - Con: heaviest test burden: the matrix must drive every surface against the visibility corpus in both directions to make the claim real.
+- **Complexity**: large
+- **Risk**: medium-high
+
+### Variant 3: Two-root enforcement with a fail-closed index column
+
+- **Approach**: Observe that every callable surface reaches page content through one of three roots β€” `listVaultPages`, the read-by-path primitive, or the search index β€” and enforce only there, with the census extended to prove no fourth root exists (mechanical sweep for direct `fs` reads of vault paths under `src/mcp/`, `src/cli/`, `src/openclaw/`). The index gains a per-document visibility column written at index time; query-side filtering treats a missing/unreadable value as private (fail closed), which makes the pre-existing-tagged-page population self-healing β€” stale fastpath-skipped rows have no column, so they are withheld immediately and correctly reclassified on the next content read, with a one-time persisted store marker (not `indexRevision`, which is only a cache generation) forcing full frontmatter re-examination once. Private pages stay indexed but flagged, so the transport-keyed `disclosure` can lift the filter for local callers without a segregated store; the indexer skip-vs-delete trap (`seen.add` at `indexer.ts:390`) never arises because nothing is skipped.
+- **Trade-offs**:
+ - Pro: smallest enforcement surface β€” three choke points plus a census that proves their sufficiency; the 68 registry rows flip to `covered` by root, each citing which root covers it.
+ - Pro: index handling is the cleanest of the three: fail-closed column solves the mtime-fastpath legacy population without a purge/migration dance, and trusted-local search over private pages keeps working.
+ - Con: private page bodies remain in `chunks`/`chunk_fts` at rest β€” anyone with file access to the store reads them; this must be stated plainly (it is the same trust boundary as the vault files themselves, but it is a fact, not nothing).
+ - Con: the whole guarantee hangs on the root-closure census being right; a surface that shells out or re-implements a walk escapes until the census learns that shape.
+ - Con: read-by-path root must refuse with the same `not found` an absent page produces, and that message-identity must be asserted in the matrix.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Recommended: Variant 3
+**Rationale**: Variant 3 delivers Variant 1's safe-by-construction property at a fraction of the signature churn, fits comfortably inside the 50–70 file wave, and is the only variant whose index-side story respects all four verified indexer facts without a fragile purge path β€” the fail-closed column turns the pre-existing-private-page obligation from a migration into a default. It subsumes `applyVisibilityScope` naturally (the search root is one of the three choke points), and its residual risk β€” trusting the root-closure census β€” is exactly the mechanism this project has already chosen and shipped for population claims, so extending the census to prove "no fourth root" is idiomatic rather than novel.
+
+---
+
+## Orchestrator decision: Variant 3, with one mechanism corrected
+
+Variant 3 is adopted. Its central insight is the one that survives contact
+with the source: every callable surface in the registry reaches page content
+through one of three roots, so enforcement belongs at those roots and the
+census - the instrument this project has already chosen and shipped for
+population claims - is extended to prove no fourth root exists. That is
+Variant 1's safe-by-construction property without Variant 1's signature churn
+through seventeen `listVaultPages` call sites and every tool that builds a
+core call, and it is the opposite of Variant 2, which leaves enforcement
+distributed across 68 sites forever and puts every future surface one
+forgotten predicate away from a leak. Variant 2 also fails the project's
+one-rule-one-spelling convention on its face.
+
+One mechanism in Variant 3 is refuted and is replaced rather than adopted.
+
+The variant proposes that a missing index column value be read as private,
+calling the pre-existing tagged-page population "self-healing" and claiming
+this dissolves the mtime-fastpath obligation into a default. Checked against
+source, it does the opposite. `applyMigrations`
+(`src/core/search/schema.ts:773`) adds a column with NULL for every row that
+already exists, and `assertSchemaIsCurrent`
+(`src/core/search/store/lifecycle.ts:123-131`) admits a migrated index
+without any reindex. So on upgrade every document in every vault would read as
+private - including the overwhelming majority of vaults that have never set
+`visibility:` at all - and every search would return nothing until the
+operator ran a full reindex they were never told they needed. That is a
+silent, total capability blackout, and it breaks the wave's own stated
+zero-behaviour-change constraint.
+
+The replacement is smaller than the thing it replaces. Migration 12
+backfills. `packBlocks` (`src/core/search/chunker.ts:312-330`) emits a page's
+frontmatter as its own chunk, whole and without overlap, at `chunk_index = 0`
+- a structural fact `src/core/search/store/visibility-tag.ts` already relies
+on and `tests/core/search/visibility-tag-presence.test.ts` already pins. The
+migration parses that stored frontmatter for every existing document and
+writes the column with no vault walk and no operator action. The legacy
+population is then gone rather than deferred, and NULL narrows to what it
+should always have meant: a page whose frontmatter the index genuinely cannot
+produce - unterminated frontmatter, which `chunker.ts:137-141` omits, or a
+document with no chunks. That population is tiny, it is the correct thing to
+fail closed on, and `search check` reports its count rather than absorbing it.
+
+Two smaller amendments to the variant as written:
+
+- Variant 3 says private page bodies "remain in `chunks`/`chunk_fts` at rest"
+ as a con to be stated plainly. Adopted, and it is also a deliberate product
+ decision rather than only a residue: excluding private pages from the index
+ would take an operator's own private notes out of their own local search.
+ The registry's existing `index_store` row already states the storage fact
+ and is kept, reworded.
+- Variant 3 does not mention the `seen.add` trap. It is load-bearing for the
+ choice: `indexer.ts:390` marks a path seen before the content read, so a
+ "skip private pages" written as a `continue` would leave stale chunks that
+ the deletion sweep at `indexer.ts:537-540` never purges. Marking rather than
+ skipping avoids it, which is a second, independent reason for the column.
+
+### Why not Variant 1
+
+Safe by construction and honestly assessed by the consultant, but it threads a
+disclosure parameter from three transports through `ServerContext` into core
+primitives and out across most of the seventeen `listVaultPages` call sites
+plus every tool that constructs a core call. The consultant's own note is the
+deciding one: the internal engine lanes - the indexer, the dedup pool, the
+link-graph repair lane - legitimately need unfiltered reads, and drawing that
+line wrong either breaks wikilink integrity or quietly re-opens the hole. The
+chosen design still passes an explicit full-disclosure value at those lanes,
+but at three roots rather than at every call site, so the line is drawn in
+three places that can be read at once instead of across the engine.
+
+### Why not Variant 2
+
+It is the most reviewable diff and the least durable boundary. Sixty-eight
+independent adoptions means sixty-eight places to re-prove the
+no-existence-oracle property on counts, aggregates and thrown messages, which
+is precisely the class of error a sweep that size invites; and the day after
+it ships, the sixty-ninth surface is one forgotten call away. This repository
+has already shipped the argument against it: `a-label-is-not-a-boundary`
+(v1.49.0) exists because ownership had two callers and every other surface
+bypassed them, and `owner-scope-refusal.ts` states in its own docblock that a
+rule with two spellings is a rule with none.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index f37e9fb9..e535f5a2 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -1637,6 +1637,53 @@ Entity-boosted retrieval and header-anchored chunking populate on the
next reindex and need no configuration. Every result carries a
`why_retrieved` list naming the scoring layers that ranked it.
+### The reserved visibility token (since v1.54.0)
+
+```text
+o2b search query --visibility <token>... narrow results to pages declaring one of these visibility tokens
+o2b search check reports how many indexed documents reserve themselves against remote
+ reads, how many enumerated note-returning surfaces still do not consult
+ the field, and how many documents hold no frontmatter the index measured
+```
+
+A vault page's `visibility:` frontmatter carries opaque, language-neutral
+tokens, and ONE of them is reserved: a page declaring it is not readable
+at `remote` reach. Reach is a transport fact rather than a caller
+argument - stdio and every command in this CLI run at `local` reach,
+because the operator is running this binary in their own shell against a
+vault they can already open in an editor, while an HTTP bind is `local`
+only on loopback. A CLI that withheld the operator's own reserved pages
+from the operator would hide data from the only party entitled to it
+while proving nothing to anyone.
+
+The rule is enforced at three read roots - the ranked search pipeline,
+the page walker, and the by-path and by-chunk-id read primitives - and an
+architecture sweep fails the suite when a file under `src/mcp/`,
+`src/cli/` or `src/openclaw/` reads a vault path directly without a
+registered reason. `--visibility` keeps its existing meaning and can only
+NARROW: it selects among the other tokens and cannot lift the reserved
+one. A vault that never wrote the reserved token behaves exactly as it
+did before.
+
+Fail-closed, in both directions that matter. A page whose file cannot be
+read - deleted, renamed, moved to a failing mount, or chmod'd between one
+call and the next - is treated as declaring the reserved token at
+`remote` reach, because an unreadable visibility claim is not the absence
+of one; at `local` reach it is kept, since the operator is the party who
+has to fix it. A withheld page is reported exactly as an absent one, and
+no result count on a read surface states how many rows were withheld -
+the only place the withheld population is named is the `o2b search check`
+diagnostic above, which the operator ran deliberately at local reach.
+
+Schema 12 adds `documents.visibility`, holding what the INDEX measured of
+each page's frontmatter, and backfills it during the migration from the
+frontmatter the index already stores - one table scan, no vault walk, no
+reindex. The column reports; the live file decides. Three states are kept
+distinct: the page's tokens, an empty list for a page that declares none,
+and unmeasured for a document the index holds no frontmatter chunk for.
+`o2b search check` reports the unmeasured population rather than counting
+it as declaring nothing.
+
## What leaves the machine unscanned (network egress)
Every export that writes a FILE - `brain export`, `brain explorer --export`,
diff --git a/docs/mcp.md b/docs/mcp.md
index 503705c6..cc20e1f0 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1273,3 +1273,38 @@ log line is machine-composed rather than authored.
tension warnings and the owner-scope observation now reach the caller as
`brain_pre_compress_pack` has always passed them, absent when empty. No new
tool - the surface stays at 113.
+- Since v1.54.0 a page may RESERVE itself against remote reads, and the
+ reservation is enforced rather than advisory. A vault page whose
+ `visibility:` frontmatter carries the reserved token is not returned, not
+ counted, and not named in an error when the request arrived at `remote`
+ reach. The other visibility tokens are unchanged: they remain opaque,
+ caller-scoped view filters, and the caller's own `visibility` argument
+ still narrows exactly as before - what it can no longer do is name the
+ reserved token and be handed the page. A vault that never wrote the token
+ sees no change.
+- Since v1.54.0 the reach a request arrived at is MINTED by the transport
+ and refused when a caller supplies it. stdio mints `local`, because the
+ caller started this process and holds whatever filesystem access it runs
+ with. An HTTP bind mints from the bind host alone: loopback is `local`,
+ every other interface is `remote`. The value is set after the caller's
+ runtime options are spread, so a runtime option cannot claim a reach the
+ bind did not establish, and a `Host` header is never read for it. A
+ `tools/call` carrying a reach-shaped argument is refused with `-32602`,
+ the refusal token `caller-supplied-reach`, and structured `data`
+ (`tool`, `refused_arguments`, `reserved_argument_names`). The check runs
+ ahead of the unknown-argument gate and does not consult the tool's
+ schema, so an open schema is covered too; argument names are compared
+ case-folded and separator-free, so `reach`, `transport_reach` and
+ `transport-reach` are one argument rather than three. `disclosure` is
+ deliberately not reserved - it is the unrelated result-depth mode on the
+ recall surfaces.
+- Since v1.54.0 a withheld page is reported exactly as an absent one. On
+ the key-addressed reads - a chunk id, a preference id, the templated
+ `osb://` readers - the message is byte-identical to the one an absent
+ subject produces, because both key spaces are enumerable and a
+ distinguishable refusal would be an existence oracle over exactly the
+ population the boundary hides. What the `local` bypass proves is
+ filesystem-equivalent access, or a request that originated on this host.
+ It does NOT prove operator intent: a remote host can spawn a stdio
+ subprocess. The alternative - no bypass at all - would take an operator's
+ own reserved notes away from the operator's own shell.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 5211fbab..300cdbc5 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.53.1",
+ "version": "1.54.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/openclaw/index.js b/openclaw/index.js
index a719b9c5..53c7b8b5 100644
--- a/openclaw/index.js
+++ b/openclaw/index.js
@@ -3115,6 +3115,33 @@ function vaultRelative(target, vault) {
return rel.split(/[\\/]/).filter((p) => p.length > 0).join(posix.sep);
}
+// src/core/graph/transport-reach.ts
+var TRANSPORT_REACH = Object.freeze({
+ local: "local",
+ remote: "remote"
+});
+var TRANSPORT_REACHES = Object.freeze([
+ TRANSPORT_REACH.local,
+ TRANSPORT_REACH.remote
+]);
+var MAINTENANCE_LANE_REACH = TRANSPORT_REACH.local;
+
+// src/core/graph/visibility.ts
+function normToken(raw) {
+ return raw.normalize("NFC").trim().toLowerCase();
+}
+function pageVisibility(meta) {
+ const v = meta["visibility"];
+ const list = Array.isArray(v) ? v : typeof v === "string" && v.length > 0 ? [v] : [];
+ return list.map((s) => normToken(String(s))).filter((s) => s.length > 0);
+}
+var REMOTE_DENY_VISIBILITY_TOKEN = "private";
+function isRemotelyReadable(pageTags, reach) {
+ if (reach === TRANSPORT_REACH.local)
+ return true;
+ return !pageTags.includes(REMOTE_DENY_VISIBILITY_TOKEN);
+}
+
// src/core/vault.ts
var FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
var FRONTMATTER_KEY_PATTERN = "[a-zA-Z_][a-zA-Z0-9_-]*";
@@ -3236,14 +3263,18 @@ function clipNoticeLine(line) {
return line.length <= NOTICE_LINE_MAX ? line : line.slice(0, NOTICE_LINE_MAX) + NOTICE_LINE_ELLIPSIS;
}
var LIST_VAULT_PAGES_SITE = "vault.listVaultPages";
-function listVaultPages(vaultDir, opts = {}) {
+var UNMEASURABLE_PAGE_VISIBILITY = Object.freeze([
+ REMOTE_DENY_VISIBILITY_TOKEN
+]);
+function listVaultPages(vaultDir, opts) {
const skipDirs = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
const skipFiles = new Set((opts.skipFiles ?? DEFAULT_SKIP_FILES).map((f) => f.toLowerCase()));
- const pages = [];
- walk(vaultDir, vaultDir, skipDirs, skipFiles, pages, {
+ const walked = [];
+ walk(vaultDir, vaultDir, skipDirs, skipFiles, walked, {
sink: opts.notices,
site: opts.site ?? LIST_VAULT_PAGES_SITE
});
+ const pages = walked.filter((w) => isRemotelyReadable(w.unreadable ? UNMEASURABLE_PAGE_VISIBILITY : pageVisibility(w.page.metadata), opts.reach)).map((w) => w.page);
pages.sort((a, b) => a.title.toLowerCase().localeCompare(b.title.toLowerCase()));
return pages;
}
@@ -3285,7 +3316,10 @@ function walk(root, dir, skipDirs, skipFiles, out, notices) {
notices.sink.push(...pageNotices);
const titleVal = meta["title"];
const title = typeof titleVal === "string" && titleVal ? titleVal : stem(entry.name);
- out.push({ title, path: full, metadata: meta });
+ out.push({
+ page: { title, path: full, metadata: meta },
+ unreadable: pageNotices.some((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable)
+ });
}
}
function stripQuotes(s) {
@@ -3441,6 +3475,7 @@ function vaultPathField(ctx) {
}
// src/openclaw/index.ts
+var OPENCLAW_TRANSPORT_REACH = TRANSPORT_REACH.remote;
function resolveVaultPath(api) {
const cfg = api.pluginConfig ?? {};
return cfg.vault || process.env["VAULT_DIR"] || ".";
@@ -3510,7 +3545,7 @@ var openclaw_default = definePluginEntry({
const limit = typeof params["limit"] === "number" ? params["limit"] : 50;
if (limit < 1 || limit > 500)
throw new Error("argument 'limit' must be between 1 and 500");
- const pages = listVaultPages(vault).filter((p) => vaultPageInStatusScope(p.metadata, ENTITY_STATUS_SCOPE.readable));
+ const pages = listVaultPages(vault, { reach: OPENCLAW_TRANSPORT_REACH }).filter((p) => vaultPageInStatusScope(p.metadata, ENTITY_STATUS_SCOPE.readable));
const needle = pattern ? pattern.toLowerCase() : null;
const matched = (needle === null ? pages : pages.filter((p) => p.title.toLowerCase().includes(needle))).slice(0, limit).map((p) => ({
title: p.title,
diff --git a/package.json b/package.json
index 52e851ed..1d4626fb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.53.1",
+ "version": "1.54.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 d4a34e94..15e65a3d 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.53.1"
+version: "1.54.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 0bd8b3c4..c4d3bf57 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.53.1",
+ "version": "1.54.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 d4a34e94..15e65a3d 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.53.1"
+version: "1.54.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 e6dda740..c36bdf99 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.53.1"
+version = "1.54.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/verbs/backlinks.ts b/src/cli/brain/verbs/backlinks.ts
index 8e980d83..65545c22 100644
--- a/src/cli/brain/verbs/backlinks.ts
+++ b/src/cli/brain/verbs/backlinks.ts
@@ -2,6 +2,8 @@ import { buildBacklinkIndex } from "../../../core/brain/backlinks.ts";
import { gatedOwnerScopeView } from "../../../core/brain/owner-scope-view.ts";
import { normaliseWikilinkTarget } from "../../../core/brain/wikilink.ts";
import { brainVerbContext, fail, parse, resolveBrainAgent } from "../helpers.ts";
+import { reachView } from "../../../core/brain/reach-view.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
/**
* The one sentence that turns a count into a measurement.
@@ -36,7 +38,14 @@ export async function cmdBrainBacklinks(argv: string[]): Promise<number> {
vault,
gatedOwnerScopeView(vault, resolveBrainAgent(flags, config)).scope,
);
- const refs = index.get(target) ?? [];
+ // The reserved-token rule, asked here as `brain_backlinks` asks it, so
+ // the two mirrors cannot drift on what a ref discloses. This verb runs
+ // in the operator's own shell, so the view admits everything - by
+ // decision rather than by omission.
+ const view = reachView(vault, CLI_TRANSPORT_REACH);
+ const refs = view.visible(target)
+ ? (index.get(target) ?? []).filter((r) => view.visible(r.source))
+ : [];
if (flags["json"]) {
process.stdout.write(
diff --git a/src/cli/brain/verbs/benchmark.ts b/src/cli/brain/verbs/benchmark.ts
index 0b959b08..e07d7d90 100644
--- a/src/cli/brain/verbs/benchmark.ts
+++ b/src/cli/brain/verbs/benchmark.ts
@@ -17,6 +17,7 @@ import { isoSecond } from "../../../core/brain/time.ts";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { SearchError } from "../../../core/search/types.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
const USAGE =
"usage: o2b brain benchmark run --dataset <path> [--k N] [--expand] [--vault <path>] [--json]";
@@ -59,6 +60,7 @@ export async function cmdBrainBenchmark(argv: string[]): Promise<number> {
const report = await runRecallBenchmark(searchConfig, dataset, {
...(k !== undefined ? { k } : {}),
expand: flags["expand"] === true,
+ transportReach: CLI_TRANSPORT_REACH,
});
try {
appendMetric(vault, {
diff --git a/src/cli/brain/verbs/clusters.ts b/src/cli/brain/verbs/clusters.ts
index bddf725c..5d84be02 100644
--- a/src/cli/brain/verbs/clusters.ts
+++ b/src/cli/brain/verbs/clusters.ts
@@ -47,6 +47,7 @@ import { emitNextStep, type AdvisoryStream } from "../../advisory-rail.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
const USAGE =
"usage: o2b brain clusters run [--min-size N] [--batch-size N] [--if-stale] [--progress] | " +
@@ -62,7 +63,7 @@ const CLUSTERS_DIR_REL = join("Brain", "clusters");
*/
function clustersStaleness(vault: string, nowMs: number): StalenessResult {
const clustersDir = join(vault, CLUSTERS_DIR_REL);
- const inputs = listVaultPages(vault)
+ const inputs = listVaultPages(vault, { reach: CLI_TRANSPORT_REACH })
.map((p) => p.path)
.filter((p) => !p.startsWith(clustersDir));
const outputs = existsSync(clustersDir)
diff --git a/src/cli/brain/verbs/deep-synthesis.ts b/src/cli/brain/verbs/deep-synthesis.ts
index c7c86da2..5b846f4e 100644
--- a/src/cli/brain/verbs/deep-synthesis.ts
+++ b/src/cli/brain/verbs/deep-synthesis.ts
@@ -16,6 +16,7 @@ import {
import { createTriggers } from "../../../core/brain/triggers/store.ts";
import { resolveSearchConfig, SearchError } from "../../../core/search/index.ts";
import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
export async function cmdBrainDeepSynthesis(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
@@ -41,7 +42,11 @@ export async function cmdBrainDeepSynthesis(argv: string[]): Promise<number> {
const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
const searchConfig = resolveSearchConfig({ vault, configPath: config });
const now = new Date();
- const report = await deepSynthesis(searchConfig, topic, { now, limit });
+ const report = await deepSynthesis(searchConfig, topic, {
+ now,
+ limit,
+ transportReach: CLI_TRANSPORT_REACH,
+ });
let enqueued = 0;
if (flags["triggers"] === true) {
diff --git a/src/cli/brain/verbs/file-context.ts b/src/cli/brain/verbs/file-context.ts
index 83ed4b09..e36b5bd6 100644
--- a/src/cli/brain/verbs/file-context.ts
+++ b/src/cli/brain/verbs/file-context.ts
@@ -1,6 +1,7 @@
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { fileContextRecall } from "../../../core/brain/file-recall.ts";
import { brainVerbContext, parse, usageError } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
/**
* `o2b brain file-context <file-path> [--limit N] [--min-bytes N] [--vault PATH] [--json]`
@@ -34,6 +35,7 @@ export async function cmdBrainFileContext(argv: string[]): Promise<number> {
const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
const result = await fileContextRecall(searchConfig, {
+ transportReach: CLI_TRANSPORT_REACH,
filePath,
...(limit !== undefined ? { limit } : {}),
...(minBytes !== undefined ? { minBytes } : {}),
diff --git a/src/cli/brain/verbs/query.ts b/src/cli/brain/verbs/query.ts
index 0c17d731..c10e4bbc 100644
--- a/src/cli/brain/verbs/query.ts
+++ b/src/cli/brain/verbs/query.ts
@@ -35,6 +35,7 @@ import {
renderQueryTopicText,
usageError,
} from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
/** The two point-in-time flags, which only the expiry filter reads. */
const AS_OF_FLAG = "--at";
@@ -107,6 +108,11 @@ export async function cmdBrainQuery(argv: string[]): Promise<number> {
if (flags["topic"]) {
const topicOptions: QueryByTopicOptions = {
showExpired,
+ // The operator's own shell, stated rather than assumed: this verb
+ // asks the same selection rule `brain_query` asks, and the answer
+ // it gets is "admit everything" because of who the caller is, not
+ // because nobody asked.
+ transportReach: CLI_TRANSPORT_REACH,
...(asOf !== null ? { now: asOf } : {}),
};
const out = queryByTopic(vault, String(flags["topic"]), topicOptions);
diff --git a/src/cli/brain/verbs/sgrep.ts b/src/cli/brain/verbs/sgrep.ts
index 992ed8f2..862f43d5 100644
--- a/src/cli/brain/verbs/sgrep.ts
+++ b/src/cli/brain/verbs/sgrep.ts
@@ -9,6 +9,7 @@
import { defaultConfigPath } from "../../../core/config.ts";
import { resolveSearchConfig, search, SearchError } from "../../../core/search/index.ts";
import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
export async function cmdBrainSgrep(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
@@ -41,6 +42,7 @@ export async function cmdBrainSgrep(argv: string[]): Promise<number> {
const outcome = await search(searchConfig, {
query,
limit,
+ transportReach: CLI_TRANSPORT_REACH,
keywordOnly: flags["keyword-only"] === true,
...(pathPrefix !== undefined ? { pathPrefix } : {}),
...(typeof flags["agent-scope"] === "string"
diff --git a/src/cli/brain/verbs/tune.ts b/src/cli/brain/verbs/tune.ts
index c17af724..2c4e4527 100644
--- a/src/cli/brain/verbs/tune.ts
+++ b/src/cli/brain/verbs/tune.ts
@@ -22,6 +22,7 @@ import { SearchError } from "../../../core/search/types.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
const USAGE =
"usage: o2b brain tune run --dataset <path> [--k N] | status | reset [--vault <path>] [--json]";
@@ -99,6 +100,7 @@ export async function cmdBrainTune(argv: string[]): Promise<number> {
const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
const now = new Date();
const report = await tuneRecall(searchConfig, dataset, {
+ transportReach: CLI_TRANSPORT_REACH,
...(k !== undefined ? { k } : {}),
now,
});
diff --git a/src/cli/main.ts b/src/cli/main.ts
index d7d7a28d..9b913e06 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -68,6 +68,7 @@ import {
import { CLI_COMMAND_MANIFEST, manifestForJson } from "./command-manifest.ts";
import { COMPLETION_SHELLS, isCompletionShell, renderCompletions } from "./completions.ts";
import { MCPServer } from "../mcp/server.ts";
+import { CLI_TRANSPORT_REACH } from "./transport-reach.ts";
import { startHttp, isLoopbackHost } from "../mcp/http.ts";
import { serveStdio } from "../mcp/stdio.ts";
import { SERVER_VERSION } from "../mcp/protocol.ts";
@@ -572,7 +573,7 @@ async function cmdIndex(argv: string[]): Promise<number> {
const vault = requireVault(flags["vault"] as string | undefined, defaultConfigPath());
let pages;
try {
- pages = listVaultPages(vault);
+ pages = listVaultPages(vault, { reach: CLI_TRANSPORT_REACH });
} catch (exc) {
process.stderr.write(`error: failed to list vault pages: ${(exc as Error).message ?? exc}\n`);
return 1;
@@ -919,7 +920,11 @@ async function cmdToolCall(argv: string[]): Promise<number> {
args[k] = v;
}
}
- const server = new MCPServer({ vault, configPath: config });
+ // The CLI tool-call bridge runs in the operator's own shell against
+ // the operator's own vault, so it establishes the same reach stdio
+ // does - and for the same reason: filesystem-equivalent access is
+ // already held before the first argument is parsed.
+ const server = new MCPServer({ vault, configPath: config }, { reach: CLI_TRANSPORT_REACH });
try {
const result = await server.callTool(toolName, args);
process.stdout.write(JSON.stringify(result, null, 2) + "\n");
diff --git a/src/cli/search/verbs/check.ts b/src/cli/search/verbs/check.ts
index b825b001..5008b85b 100644
--- a/src/cli/search/verbs/check.ts
+++ b/src/cli/search/verbs/check.ts
@@ -469,23 +469,34 @@ function describePendingVectors(census: PendingVectorCensus): string {
}
/**
- * The visibility honesty finding as one operator-facing line
- * (nothing-writes-silently, unit H, form B). Both counts are the
- * registry's own numbers, read at render time - never hand-written here.
+ * The visibility honesty finding as one operator-facing line. Every
+ * number in it is a measurement read at render time - the surface counts
+ * off the registry, the document counts off the index's own column -
+ * never hand-written here.
+ *
+ * The sentence changed shape when the boundary did. It used to say the
+ * field was a caller-supplied view filter and not a privacy boundary,
+ * which was true and is no longer: the reserved token is enforced at
+ * three read roots and cannot be lifted by a caller argument. What stays
+ * is the honesty the finding was built for - the population that is still
+ * outside the boundary, and the population the index cannot measure.
*
* The line names the ENUMERATED population rather than implying it is
* the product's whole surface area. It is not: the MCP half is swept
* mechanically and its rule has stated blind spots, and the CLI half is
* hand-enumerated one row per MCP mirror. A reader who took the
* denominator for "every note-returning surface there is" would size the
- * enforcement work against a number that is a floor.
+ * remaining work against a number that is a floor.
*/
function describeVisibilityHonesty(finding: VisibilityHonestyFinding): string {
return (
- "visibility: frontmatter is a caller-supplied view filter, not a privacy boundary; " +
- `${finding.excludedSurfaceCount} of the ${finding.totalSurfaceCount} note-returning ` +
- "surfaces the visibility census enumerates do not honor it, and the census does not " +
- "claim to enumerate them all (see tests/core/architecture/visibility-surface-census.test.ts)"
+ `${finding.reservedDocumentCount} indexed document(s) reserve themselves against remote ` +
+ `reads; ${finding.excludedSurfaceCount} of the ${finding.totalSurfaceCount} note-returning ` +
+ "surfaces the visibility census enumerates still do not consult the field, and the census " +
+ "does not claim to enumerate them all " +
+ "(see tests/core/architecture/visibility-surface-census.test.ts); " +
+ `${finding.unmeasuredDocumentCount} indexed document(s) hold no frontmatter the index can ` +
+ "measure, and are reported rather than counted as declaring nothing"
);
}
diff --git a/src/cli/search/verbs/expand.ts b/src/cli/search/verbs/expand.ts
index eeec8123..ced38bbe 100644
--- a/src/cli/search/verbs/expand.ts
+++ b/src/cli/search/verbs/expand.ts
@@ -15,6 +15,7 @@ import {
resolveConfig,
VAULT_FLAGS,
} from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
export async function cmdSearchExpand(argv: ReadonlyArray<string>): Promise<number> {
const { flags } = parseFlags(argv, {
@@ -44,6 +45,7 @@ export async function cmdSearchExpand(argv: ReadonlyArray<string>): Promise<numb
try {
result = await expandHit(cfg, {
chunkId,
+ transportReach: CLI_TRANSPORT_REACH,
...(rawLimit !== undefined ? { rawLimit } : {}),
...(cursor !== undefined ? { cursor } : {}),
...(agentScope !== undefined ? { agentScope } : {}),
diff --git a/src/cli/search/verbs/learned-weights.ts b/src/cli/search/verbs/learned-weights.ts
index 62186fff..89203c7a 100644
--- a/src/cli/search/verbs/learned-weights.ts
+++ b/src/cli/search/verbs/learned-weights.ts
@@ -22,6 +22,7 @@ import {
resolveConfig,
VAULT_FLAGS,
} from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
export async function cmdSearchFeedback(argv: ReadonlyArray<string>): Promise<number> {
const { flags } = parseFlags(argv, {
@@ -41,7 +42,12 @@ export async function cmdSearchFeedback(argv: ReadonlyArray<string>): Promise<nu
throw new CliError("--verdict must be 'up' or 'down'");
}
const cfg = resolveConfig(flags);
- const outcome = await captureRecallFeedback(cfg, { query, resultPath, verdict });
+ const outcome = await captureRecallFeedback(cfg, {
+ query,
+ resultPath,
+ verdict,
+ transportReach: CLI_TRANSPORT_REACH,
+ });
if (flagBoolean(flags, "json")) {
process.stdout.write(
JSON.stringify({
diff --git a/src/cli/search/verbs/query.ts b/src/cli/search/verbs/query.ts
index fb71f434..337995b1 100644
--- a/src/cli/search/verbs/query.ts
+++ b/src/cli/search/verbs/query.ts
@@ -28,6 +28,7 @@ import {
resolveConfigPath,
VAULT_FLAGS,
} from "../helpers.ts";
+import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
/** Both malformed `--property` shapes report the same way. */
function propertyFormatError(entry: string): CliError {
@@ -127,6 +128,10 @@ export async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<numbe
...(properties !== undefined ? { properties } : {}),
...(degreeFilters !== undefined ? { degreeFilters } : {}),
...(visibility !== undefined && visibility.length > 0 ? { visibility } : {}),
+ // The operator's own shell against the operator's own vault; carried
+ // into the cross-vault union below on the same options object, so a
+ // federated CLI query is bound by the same rule.
+ transportReach: CLI_TRANSPORT_REACH,
// Owner-scope isolation (context-integrity-gates, Unit A): an
// owner-private page is returned only to its own scope. Omitting the
// flag applies no ownership filtering at all.
diff --git a/src/cli/transport-reach.ts b/src/cli/transport-reach.ts
new file mode 100644
index 00000000..1ac93a2a
--- /dev/null
+++ b/src/cli/transport-reach.ts
@@ -0,0 +1,17 @@
+/**
+ * The reach every command in this CLI runs at.
+ *
+ * `local`, for the same reason the stdio transport mints it
+ * (`src/mcp/stdio.ts`): the operator is running this binary in their own
+ * shell, against a vault they can already open in an editor. A CLI that
+ * withheld the operator's own reserved pages from the operator would be
+ * hiding data from the only person entitled to it, while proving nothing
+ * to anyone.
+ *
+ * Named once here rather than spelled at each verb, so the claim each
+ * verb makes about its caller is the same claim.
+ */
+
+import { TRANSPORT_REACH, type TransportReach } from "../core/graph/transport-reach.ts";
+
+export const CLI_TRANSPORT_REACH: TransportReach = TRANSPORT_REACH.local;
diff --git a/src/core/bench/failure-modes.ts b/src/core/bench/failure-modes.ts
index 0d998c6c..f9d09726 100644
--- a/src/core/bench/failure-modes.ts
+++ b/src/core/bench/failure-modes.ts
@@ -88,6 +88,7 @@
import { estimateTokens } from "../brain/text/tokenizer.ts";
import type { RecallInjectDecision, RecallResultSet } from "../brain/recall-inject.ts";
import { resolveSearchConfig, search } from "../search/index.ts";
+import { TRANSPORT_REACH } from "../graph/transport-reach.ts";
/**
* How one proactive-recall decision failed, or nothing when it was right.
@@ -135,7 +136,14 @@ export function benchRecallRetriever(
limit: number,
): (query: string) => Promise<RecallResultSet> {
return async (query) => {
- const outcome = await search(config, { query, limit });
+ // Internal measurement lane: nothing here reaches a remote caller, so
+ // it measures the whole corpus. A lane that stopped seeing reserved
+ // pages would report a smaller vault than the one it is measuring.
+ const outcome = await search(config, {
+ query,
+ limit,
+ transportReach: TRANSPORT_REACH.local,
+ });
return Object.freeze({
candidates: Object.freeze(
outcome.results.map((result) =>
diff --git a/src/core/bench/phases.ts b/src/core/bench/phases.ts
index 7da7d03a..d97a66a9 100644
--- a/src/core/bench/phases.ts
+++ b/src/core/bench/phases.ts
@@ -17,6 +17,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { packContext } from "../brain/context-pack.ts";
+import { TRANSPORT_REACH } from "../graph/transport-reach.ts";
import { loadNormalizedContinuityRecords } from "../brain/continuity/read-model.ts";
import type { ContinuityRecord } from "../brain/continuity/types.ts";
import { extractPreCompactRecords } from "../brain/pre-compact-extract.ts";
@@ -54,6 +55,15 @@ import {
type BenchReport,
} from "./types.ts";
+/**
+ * The reach the benchmark harness runs its queries at.
+ *
+ * Local: a bench run measures this vault's own corpus and hands no page
+ * to any caller, so a run that stopped seeing reserved pages would score
+ * a smaller vault than the one under test.
+ */
+const BENCH_REACH = TRANSPORT_REACH.local;
+
export interface BenchRunOptions {
readonly fixture: BenchFixture;
readonly runsDir: string;
@@ -133,7 +143,7 @@ export async function runMemoryBench(opts: BenchRunOptions): Promise<BenchReport
// the FTS index exists before any timed retrieval.
if (!phaseDone(checkpoint, "index")) {
const config = benchSearchConfig(vault);
- await search(config, { query: "warmup", limit: 1 });
+ await search(config, { query: "warmup", limit: 1, transportReach: BENCH_REACH });
checkpoint = completeBenchPhase(run.runDir, checkpoint, "index");
}
@@ -184,6 +194,7 @@ async function retrieveQuestion(
const outcome = await search(config, {
query: question.query ?? "",
limit: question.top_k ?? 5,
+ transportReach: BENCH_REACH,
});
return {
id: question.id,
diff --git a/src/core/brain/artifact-ref-view.ts b/src/core/brain/artifact-ref-view.ts
new file mode 100644
index 00000000..ab759cc6
--- /dev/null
+++ b/src/core/brain/artifact-ref-view.ts
@@ -0,0 +1,227 @@
+/**
+ * What one caller may see, over the REFERENCES a report row carries
+ * rather than over a ranked search result.
+ *
+ * Extracted from `./owner-scope-view.ts` when a second rule - the
+ * transport-reach visibility boundary - needed the same adapter. The
+ * ownership rule and the visibility rule are different questions with
+ * different answers, but the plumbing between "a row names `[[pref-x]]`"
+ * and "here is the vault-relative path of `pref-x`" is one piece of
+ * machinery, and a second copy of it would be a second place for a
+ * directory to go missing.
+ *
+ * Neither this module nor its bindings is a registry: each one delegates
+ * the per-PATH decision to the single place that rule meets the
+ * filesystem (`isPathOwnerVisible` / `isPathReadableAtReach`, both in
+ * `src/core/search/result-filters.ts`), so a report-shaped surface and a
+ * ranked one cannot drift on what "hidden" means - including the
+ * unreadable-file verdict, which an empty frontmatter map cannot express.
+ *
+ * ## Two conventions every binding inherits
+ *
+ * FAIL CLOSED, in whichever direction its rule fails closed. A page whose
+ * file cannot be read has an unknowable answer, and an unreadable claim
+ * is not the absence of one.
+ *
+ * IDENTICAL TO ABSENT. A withheld row is dropped and nothing counts it: a
+ * count would tell the caller that a row it may not see exists, which is
+ * the existence leak the search side already avoids. So no surface using
+ * one of these views reports how many rows it withheld.
+ */
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+
+import type { FrontmatterCache } from "../search/result-filters.ts";
+import { BRAIN_SOURCES_REL, brainDirs } from "./paths.ts";
+import { ANCHORED_WIKILINK_RE, stripWikilinkDecoration } from "./wikilink.ts";
+
+/** The `.md` extension every Brain artifact id resolves through. */
+const MARKDOWN_EXT = ".md";
+
+/**
+ * A reference a report row carries: either a vault-relative path
+ * (`Brain/preferences/pref-x.md`, `notes/y.md`) or a bare Brain artifact
+ * id (`pref-x`, `ret-y`, `sig-2026-05-01-z`), optionally spelled as a
+ * wikilink (`[[pref-x]]`, `[[notes/y.md]]`).
+ *
+ * `null` / `undefined` / empty are accepted and read as "this row names
+ * nothing here", which is visible: a row with no subject cannot disclose
+ * one.
+ */
+export type ArtifactRef = string | null | undefined;
+
+/**
+ * Strip the wikilink brackets a report row may have kept around its
+ * reference, leaving the target verbatim.
+ *
+ * The brackets are SYNTAX, not part of the reference: a retirement's
+ * `retired_by`, a dream transition's `link` and an evidence row's
+ * `artifact` all carry `[[…]]` straight out of frontmatter or a log
+ * body, and `[[Brain/preferences/pref-x.md]]` names exactly the page
+ * `Brain/preferences/pref-x.md`. Before this, such a reference matched
+ * neither branch below and the row failed OPEN.
+ *
+ * Deliberately NOT `parseWikilinkRich`: that normaliser collapses folder
+ * segments and drops `.md`, which turns a path-shaped link into a bare
+ * basename that resolves to no artifact - the same fail-open by a longer
+ * route.
+ *
+ * The alias and anchor DO come off, through the decoration-only half of
+ * that normaliser. Leaving them on was a fail-open with a comment on it:
+ * `pref-x|alias`, `pref-x#Raw` and
+ * `Brain/preferences/pref-x.md|the rule` end in neither `.md` nor an id
+ * any directory holds, so they resolved to nothing and their rows passed
+ * unconditionally - and these are not hypothetical spellings, they are
+ * what `brain_apply_evidence` documents for its own `artifact` argument.
+ * Cutting decoration can only ever SHORTEN the target, so a reference
+ * that resolved before still resolves and one that did not may now.
+ */
+function unbracket(ref: string): string {
+ const match = ANCHORED_WIKILINK_RE.exec(ref.trim());
+ return stripWikilinkDecoration(match === null ? ref : match[1]!);
+}
+
+/** One rule, bound to one vault, asked over references. */
+export interface ArtifactRefView {
+ /**
+ * True when this view cannot hide anything, so a caller may skip the
+ * work of asking it.
+ *
+ * It exists for the surfaces whose filtered form is not byte-identical
+ * to their unfiltered one - a rendered log day is split on its event
+ * headings and rejoined - and that must stay verbatim when no rule is
+ * live. Read as "is there anything to ask", never as "is the caller
+ * entitled": the decision is always {@link ArtifactRefView.visible}.
+ */
+ readonly filtersNothing: boolean;
+ /** May the caller see the artifact or page this reference names? */
+ readonly visible: (ref: ArtifactRef) => boolean;
+ /**
+ * May the caller see a row that names ALL of these? One hidden
+ * reference hides the row: a row survives only when every artifact it
+ * would disclose is one the caller may already see.
+ */
+ readonly row: (...refs: ReadonlyArray<ArtifactRef>) => boolean;
+ /** Drop the rows whose references are not all visible. */
+ readonly keep: <T>(
+ rows: ReadonlyArray<T>,
+ refsOf: (row: T) => ReadonlyArray<ArtifactRef>,
+ ) => ReadonlyArray<T>;
+}
+
+/** A view that hides nothing, allocated once. */
+export const UNFILTERED_ARTIFACT_REFS: ArtifactRefView = Object.freeze({
+ filtersNothing: true,
+ visible: () => true,
+ row: () => true,
+ keep: <T>(rows: ReadonlyArray<T>) => rows,
+});
+
+/**
+ * Resolve a bare Brain artifact id to its vault-relative path, or `null`
+ * when no artifact of that id is on disk.
+ *
+ * ## Why the directory list is the whole boundary
+ *
+ * `visible()` reads an id that resolves to no file as "this row names
+ * nothing that could be hidden" and lets the row through. That reading is
+ * true only for ids this function would have FOUND had the artifact
+ * existed - so every directory omitted here is a directory whose pages
+ * are silently unclassifiable, and every binding's fail-closed promise
+ * turns into a fail-open one for exactly those pages. The list is
+ * therefore every `Brain/` directory holding id-addressable Markdown:
+ *
+ * - `preferences` / `retired` carry `owner:` through the preference
+ * writer, and carry `visibility:` wherever an operator wrote one;
+ * - `inbox` / `processed` / `pending` carry whatever an operator or an
+ * importer wrote into a signal's frontmatter;
+ * - `sources` (`src-<slug>.md`) and `entities` are taggable the same
+ * way, and `brain_search_by_source` already filters the first of them
+ * on the search side - so an id-shaped reference to one reaching a
+ * view here and passing was the two halves disagreeing.
+ *
+ * `log` is deliberately absent - a log shard is named by date, is shared
+ * by construction, and carries no per-page claim to read. `bases` holds
+ * `.base` view definitions rather than Markdown pages, and `snapshots`
+ * holds dated copies addressed by path rather than by id.
+ */
+function artifactPath(vault: string, id: string): string | null {
+ const dirs = brainDirs(vault);
+ for (const dir of [
+ dirs.preferences,
+ dirs.retired,
+ dirs.inbox,
+ dirs.processed,
+ dirs.pending,
+ join(vault, BRAIN_SOURCES_REL),
+ dirs.entities,
+ ]) {
+ const abs = join(dir, `${id}${MARKDOWN_EXT}`);
+ if (existsSync(abs)) return abs.slice(vault.length + 1);
+ }
+ return null;
+}
+
+/**
+ * Bind one per-path rule to one vault, as a reference-shaped view.
+ *
+ * `pathVisible` is handed the shared per-response frontmatter cache, the
+ * same sharing `search()` gives its filter stages, so a response that
+ * names the same artifact from several rows parses it once.
+ */
+export function artifactRefView(
+ vault: string,
+ pathVisible: (rel: string, cache: FrontmatterCache) => boolean,
+): ArtifactRefView {
+ const cache: FrontmatterCache = new Map();
+ // Per-response memo over the REFERENCE, beside the one over the path.
+ // Rows name the same artifact repeatedly - a log day's events about one
+ // preference, a backlink list's sources - and `artifactPath` costs one
+ // `existsSync` per Brain directory for every id-shaped string that
+ // resolves to nothing, which is the common case now that the whole
+ // payload is offered rather than four named keys.
+ const verdicts = new Map<string, boolean>();
+ const visible = (ref: ArtifactRef): boolean => {
+ if (ref === null || ref === undefined || ref.length === 0) return true;
+ const memo = verdicts.get(ref);
+ if (memo !== undefined) return memo;
+ // A reference that names a path is resolved as one; anything else is
+ // a Brain artifact id, and an id with no artifact on disk names
+ // nothing that could be hidden - see {@link artifactPath} for why
+ // that reading is only true while its directory list is complete.
+ const bare = unbracket(ref);
+ const rel =
+ bare.length === 0 ? null : bare.endsWith(MARKDOWN_EXT) ? bare : artifactPath(vault, bare);
+ const verdict = rel === null ? true : pathVisible(rel, cache);
+ verdicts.set(ref, verdict);
+ return verdict;
+ };
+ return Object.freeze({
+ filtersNothing: false,
+ visible,
+ row: (...refs: ReadonlyArray<ArtifactRef>) => refs.every(visible),
+ keep: <T>(rows: ReadonlyArray<T>, refsOf: (r: T) => ReadonlyArray<ArtifactRef>) =>
+ rows.filter((r) => refsOf(r).every(visible)),
+ });
+}
+
+/**
+ * One view that keeps a reference only when every constituent does.
+ *
+ * The rules are ANDed rather than folded: they are independent questions
+ * with independent answers, and which one dropped a row is not
+ * observable, because none of them reports a count.
+ */
+export function everyArtifactRefView(...views: ReadonlyArray<ArtifactRefView>): ArtifactRefView {
+ const live = views.filter((v) => !v.filtersNothing);
+ if (live.length === 0) return UNFILTERED_ARTIFACT_REFS;
+ const visible = (ref: ArtifactRef): boolean => live.every((v) => v.visible(ref));
+ return Object.freeze({
+ filtersNothing: false,
+ visible,
+ row: (...refs: ReadonlyArray<ArtifactRef>) => refs.every(visible),
+ keep: <T>(rows: ReadonlyArray<T>, refsOf: (r: T) => ReadonlyArray<ArtifactRef>) =>
+ rows.filter((r) => refsOf(r).every(visible)),
+ });
+}
diff --git a/src/core/brain/deep-synthesis.ts b/src/core/brain/deep-synthesis.ts
index e65ec9f1..2dafd011 100644
--- a/src/core/brain/deep-synthesis.ts
+++ b/src/core/brain/deep-synthesis.ts
@@ -21,6 +21,7 @@ import { sha256Hex } from "../integrity/digest.ts";
import { search } from "../search/search.ts";
import { walkVault } from "../search/walker.ts";
import type { BrainSearchResult, ResolvedSearchConfig } from "../search/types.ts";
+import type { TransportReach } from "../graph/transport-reach.ts";
import { buildEntityIndex } from "./entities/index-builder.ts";
import { extractWikilinkRichBodies, parseWikilinkRich } from "./link-graph/parse-wikilink.ts";
import { fileAgeMs, msToWholeDays } from "./time.ts";
@@ -231,6 +232,15 @@ export interface DeepSynthesisOptions {
* unscoped call byte-identical.
*/
readonly agentScope?: string;
+ /**
+ * How far this caller reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`) and threaded straight into
+ * {@link SearchOptions.transportReach}, so a page reserved against
+ * remote reads is withheld here on exactly the same terms it is
+ * withheld from a direct search. Omitted resolves to the narrowest,
+ * which is what a lane that established nothing should get.
+ */
+ readonly transportReach?: TransportReach;
}
const CHECKED = Object.freeze([
@@ -367,6 +377,7 @@ export async function deepSynthesis(
limit: rawLimit,
keywordOnly: true,
...(opts.agentScope !== undefined ? { agentScope: opts.agentScope } : {}),
+ ...(opts.transportReach !== undefined ? { transportReach: opts.transportReach } : {}),
});
// Dedupe chunk hits into per-document notes (best score wins), THEN
diff --git a/src/core/brain/doctor/uncertainty-probes.ts b/src/core/brain/doctor/uncertainty-probes.ts
index 83480dfe..6baee4ab 100644
--- a/src/core/brain/doctor/uncertainty-probes.ts
+++ b/src/core/brain/doctor/uncertainty-probes.ts
@@ -20,6 +20,7 @@ import { scanStaleLocks } from "../sync-lockfile.ts";
import { vaultMarkerAbsentNotice } from "../vault-identity.ts";
import type { DoctorCheck } from "./check.ts";
import { pushUncertain } from "./uncertain-stream.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
/** Site recorded on the notices the doctor's Brain-tree sweep collects. */
const DOCTOR_FRONTMATTER_SITE = "brain.doctor";
@@ -50,7 +51,11 @@ export const frontmatterUncertaintyProbe: DoctorCheck = {
const dirs = brainDirs(vault);
if (!existsSync(dirs.brain)) return;
const notices: DegradationNotice[] = [];
- listVaultPages(dirs.brain, { notices, site: DOCTOR_FRONTMATTER_SITE });
+ listVaultPages(dirs.brain, {
+ notices,
+ site: DOCTOR_FRONTMATTER_SITE,
+ reach: MAINTENANCE_LANE_REACH,
+ });
for (const notice of notices) {
// Through the shared stream, not straight onto the array: this
// walk covers the same Brain/ subtrees the hand-written sweeps do,
diff --git a/src/core/brain/file-recall.ts b/src/core/brain/file-recall.ts
index 94e7daa0..1f706f36 100644
--- a/src/core/brain/file-recall.ts
+++ b/src/core/brain/file-recall.ts
@@ -18,6 +18,7 @@ import { statSync } from "node:fs";
import { search } from "../search/search.ts";
import type { BrainSearchResult, ResolvedSearchConfig } from "../search/types.ts";
+import type { TransportReach } from "../graph/transport-reach.ts";
const DEFAULT_LIMIT = 5;
const DEFAULT_MIN_BYTES = 1500;
@@ -37,6 +38,15 @@ export interface FileContextOptions {
* unscoped call byte-identical.
*/
readonly agentScope?: string;
+ /**
+ * How far this caller reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`) and threaded straight into
+ * {@link SearchOptions.transportReach}, so a page reserved against
+ * remote reads is withheld here on exactly the same terms it is
+ * withheld from a direct search. Omitted resolves to the narrowest,
+ * which is what a lane that established nothing should get.
+ */
+ readonly transportReach?: TransportReach;
}
export interface FileContextResult {
@@ -102,6 +112,7 @@ export async function fileContextRecall(
query,
limit,
...(opts.agentScope !== undefined ? { agentScope: opts.agentScope } : {}),
+ ...(opts.transportReach !== undefined ? { transportReach: opts.transportReach } : {}),
});
return frozenResult(opts.filePath, false, null, query, outcome.results);
}
diff --git a/src/core/brain/freshness.ts b/src/core/brain/freshness.ts
index f84620af..9ea0cb82 100644
--- a/src/core/brain/freshness.ts
+++ b/src/core/brain/freshness.ts
@@ -25,6 +25,7 @@ import { isAbsolute, join } from "node:path";
import { sha256Hex } from "../integrity/digest.ts";
import { listVaultPages, parseFrontmatter } from "../vault.ts";
+import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";
/** Hash value recorded for a source that did not exist at derivation. */
export const MISSING_SOURCE_HASH = "missing";
@@ -168,7 +169,7 @@ function freshnessOf(vault: string, pagePath: string, contract: SourceStamp): Pa
* the contract. On-demand and read-only.
*/
export function scanFreshness(vault: string): FreshnessReport {
- const pages = listVaultPages(vault);
+ const pages = listVaultPages(vault, { reach: MAINTENANCE_LANE_REACH });
let withContract = 0;
let fresh = 0;
const stale: PageFreshness[] = [];
diff --git a/src/core/brain/heal-run.ts b/src/core/brain/heal-run.ts
index d4cfc948..d95d9eff 100644
--- a/src/core/brain/heal-run.ts
+++ b/src/core/brain/heal-run.ts
@@ -34,6 +34,7 @@ import {
type ProgressSink,
} from "./progress.ts";
import type { Safeguard } from "./safeguard.ts";
+import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";
/** The one stage this pass has: it walks the vault's user pages. */
const HEAL_ENRICH_STAGE = "heal-enrich";
@@ -113,7 +114,10 @@ function healEnrichmentRun(
// it - heal must never rewrite Syncthing version history, Obsidian
// config, or the trash.
const brainDir = BRAIN_ROOT_REL.split("/")[0] ?? "Brain";
- const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, brainDir] });
+ const pages = listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS, brainDir],
+ reach: MAINTENANCE_LANE_REACH,
+ });
// The stage opens with its denominator, which is why it opens HERE and
// not before the listing: the page count is the one number a reader
// wants and it does not exist until the walk returns. It still opens
diff --git a/src/core/brain/link-graph/bridge-discovery.ts b/src/core/brain/link-graph/bridge-discovery.ts
index f13ae2d9..3d229062 100644
--- a/src/core/brain/link-graph/bridge-discovery.ts
+++ b/src/core/brain/link-graph/bridge-discovery.ts
@@ -39,6 +39,7 @@ import { resolveNotePath } from "../note-path.ts";
import type { SchemaPack } from "../schema-pack.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { OPERATION, progressCounter, withProgress, type ProgressCounter } from "../progress.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
export const BRIDGE_DEFAULT_MIN_SIMILARITY = 0.8;
export const BRIDGE_DEFAULT_MAX_PROPOSALS = 10;
@@ -374,7 +375,7 @@ export function acceptBridge(
*/
function countBasenameMatches(vault: string, base: string): number {
let count = 0;
- for (const page of listVaultPages(vault)) {
+ for (const page of listVaultPages(vault, { reach: MAINTENANCE_LANE_REACH })) {
if (!vaultPageInStatusScope(page.metadata, ENTITY_STATUS_SCOPE.readable)) continue;
if (basename(page.path, ".md") === base) count++;
}
diff --git a/src/core/brain/link-graph/co-occurrence.ts b/src/core/brain/link-graph/co-occurrence.ts
index a1d06027..847c5906 100644
--- a/src/core/brain/link-graph/co-occurrence.ts
+++ b/src/core/brain/link-graph/co-occurrence.ts
@@ -29,6 +29,7 @@ import {
import type { FrontmatterMap } from "../../types.ts";
import { BRAIN_ROOT_REL } from "../paths.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
export const CO_OCCURRENCE_SCHEMA_VERSION = "o2b.cooccurrence.v1";
@@ -95,7 +96,10 @@ export function computeCoOccurrenceSuggestions(
const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
const limit = Math.max(0, Math.floor(opts.limit ?? DEFAULT_LIMIT));
- const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL] });
+ const pages = listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
+ reach: MAINTENANCE_LANE_REACH,
+ });
// pageKey -> set of canonical targets it references (for direct-link
// exclusion). targetSets in stable insertion order for hashing.
diff --git a/src/core/brain/link-graph/graph-holdout.ts b/src/core/brain/link-graph/graph-holdout.ts
index 2ac74f67..ec421e87 100644
--- a/src/core/brain/link-graph/graph-holdout.ts
+++ b/src/core/brain/link-graph/graph-holdout.ts
@@ -23,6 +23,7 @@ import { ensureInsideVault } from "../../path-safety.ts";
import { EXCLUDED_DIRS, extractWikilinks, listVaultPages, parseFrontmatter } from "../../vault.ts";
import { ENTITY_STATUS_SCOPE, vaultPageInStatusScope } from "../entities/page-scope.ts";
import { canonicalCoOccurrenceKey } from "./co-occurrence.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
/** Upper bound on the evidence hydrated from a target note. */
export const HOLDOUT_EVIDENCE_MAX_CHARS = 2000;
@@ -77,7 +78,10 @@ export interface HoldoutGateResult {
*/
function buildKeyAdjacency(vault: string): Map<string, Set<string>> {
const adjacency = new Map<string, Set<string>>();
- for (const page of listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS] })) {
+ for (const page of listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS],
+ reach: MAINTENANCE_LANE_REACH,
+ })) {
if (!vaultPageInStatusScope(page.metadata, ENTITY_STATUS_SCOPE.readable)) continue;
const sourceKey = canonicalCoOccurrenceKey(page.path);
if (sourceKey === null) continue;
diff --git a/src/core/brain/link-graph/repair-lane.ts b/src/core/brain/link-graph/repair-lane.ts
index 7eda7458..cafeca9e 100644
--- a/src/core/brain/link-graph/repair-lane.ts
+++ b/src/core/brain/link-graph/repair-lane.ts
@@ -38,6 +38,7 @@ import { ENTITY_STATUS_SCOPE, vaultPageInStatusScope } from "../entities/page-sc
import { canonicalCoOccurrenceKey, computeCoOccurrenceSuggestions } from "./co-occurrence.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import { scaffoldStub } from "../notes/scaffold-stub.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
/** Identity-strength tiers, strongest first. `inferred` is opt-in. */
export const IDENTITY_STRENGTH = Object.freeze({
@@ -408,7 +409,10 @@ interface CollectedPage {
*/
function loadPages(vault: string): CollectedPage[] {
const out: CollectedPage[] = [];
- for (const page of listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS] })) {
+ for (const page of listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS],
+ reach: MAINTENANCE_LANE_REACH,
+ })) {
if (!vaultPageInStatusScope(page.metadata, ENTITY_STATUS_SCOPE.readable)) continue;
const rel = canonicalNotePath(relative(vault, page.path));
const key = canonicalCoOccurrenceKey(rel);
diff --git a/src/core/brain/log.ts b/src/core/brain/log.ts
index c807a80d..ad4b5cee 100644
--- a/src/core/brain/log.ts
+++ b/src/core/brain/log.ts
@@ -538,3 +538,48 @@ function parseIsoUtc(timestamp: string): IsoUtcParts {
}
return { date: m[1]!, hms: `${m[2]!}:${m[3]!}:${m[4]!}` };
}
+
+/**
+ * Every artifact one log entry names, as references an
+ * {@link ArtifactRefView} can resolve.
+ *
+ * A log entry is the one record shape whose SUBJECT is another artifact:
+ * it says what was applied to which preference, over which page. Two
+ * surfaces filter log rows by what they name - the `osb://log/{date}`
+ * resource and `brain_query` - and a second copy of the answer would be
+ * how one of the two comes to disclose more than the other.
+ *
+ * EVERY string in the payload is offered, rather than a named list of
+ * keys. The list was `path` / `preference` / `signal` / `artifact`, and a
+ * census of the writers in this tree found artifact references in
+ * `target`, `subject_a`, `subject_b`, `successor`, `predecessor`,
+ * `source`, `source_path`, `note`, `file`, `files`, `retired`,
+ * `superseded_by` and `conflicts` as well - so the list was not a
+ * measurement of what a row discloses, it was a sample of it, and every
+ * key outside it made its row unconditionally visible. Enumerating a
+ * payload whose writers are open-ended is the defect, not the particular
+ * keys that were missing from the enumeration.
+ *
+ * Offering too much is SAFE in a way offering too little is not: a string
+ * that resolves to no artifact on disk is read as naming nothing and lets
+ * its row through unchanged, which is the same answer the view gives an
+ * absent key. So the fail direction of the widening is the harmless one.
+ *
+ * Array-valued keys are flattened rather than dropped.
+ * {@link BrainLogEntryPayload} is `string | ReadonlyArray<string>` and
+ * `parseLogDay` produces an array whenever a key repeats or uses the
+ * indented sub-bullet form - so a `typeof === "string"` test answered
+ * `undefined` for a real multi-artifact reference, which the view reads
+ * as "names nothing".
+ */
+export function logEntryArtifactRefs(entry: BrainLogEntry): ReadonlyArray<string | undefined> {
+ const body = (entry.body ?? {}) as Record<string, unknown>;
+ const refs: Array<string | undefined> = [];
+ for (const value of Object.values(body)) {
+ if (typeof value === "string") refs.push(value);
+ else if (Array.isArray(value)) {
+ for (const item of value) if (typeof item === "string") refs.push(item);
+ }
+ }
+ return refs;
+}
diff --git a/src/core/brain/owner-scope-view.ts b/src/core/brain/owner-scope-view.ts
index 7b5f4098..298fe5a4 100644
--- a/src/core/brain/owner-scope-view.ts
+++ b/src/core/brain/owner-scope-view.ts
@@ -58,122 +58,26 @@
* it is deliberately not claimed here until it exists.
*/
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-
-import { isPathOwnerVisible, type FrontmatterCache } from "../search/result-filters.ts";
-import { BRAIN_SOURCES_REL, brainDirs } from "./paths.ts";
+import { isPathOwnerVisible } from "../search/result-filters.ts";
+import {
+ UNFILTERED_ARTIFACT_REFS,
+ artifactRefView,
+ type ArtifactRef,
+ type ArtifactRefView,
+} from "./artifact-ref-view.ts";
import { resolveOwnerScopeDelivery } from "./preferences-collect.ts";
-import { ANCHORED_WIKILINK_RE } from "./wikilink.ts";
-
-/** The `.md` extension every Brain artifact id resolves through. */
-const MARKDOWN_EXT = ".md";
/**
- * A reference a report row carries: either a vault-relative path
- * (`Brain/preferences/pref-x.md`, `notes/y.md`) or a bare Brain artifact
- * id (`pref-x`, `ret-y`, `sig-2026-05-01-z`), optionally spelled as a
- * wikilink (`[[pref-x]]`, `[[notes/y.md]]`).
- *
- * `null` / `undefined` / empty are accepted and read as "this row names
- * nothing here", which is visible: a row with no subject cannot disclose
- * one.
+ * A reference a report row carries. The reference grammar - paths, bare
+ * ids, wikilink brackets - is shared with every other rule asked this
+ * way; see {@link ArtifactRef}.
*/
-export type OwnerScopeRef = string | null | undefined;
-
-/**
- * Strip the wikilink brackets a report row may have kept around its
- * reference, leaving the target verbatim.
- *
- * The brackets are SYNTAX, not part of the reference: a retirement's
- * `retired_by`, a dream transition's `link` and an evidence row's
- * `artifact` all carry `[[…]]` straight out of frontmatter or a log
- * body, and `[[Brain/preferences/pref-x.md]]` names exactly the page
- * `Brain/preferences/pref-x.md`. Before this, such a reference matched
- * neither branch below and the row failed OPEN.
- *
- * Deliberately NOT {@link parseWikilinkRich}: that normaliser collapses
- * folder segments and drops `.md`, which turns a path-shaped link into a
- * bare basename that resolves to no artifact - the same fail-open by a
- * longer route. Only the brackets come off; the anchor / alias
- * decoration inside them is handled by the id-resolution step, which
- * simply finds no file and treats the row as naming nothing.
- */
-function unbracket(ref: string): string {
- const match = ANCHORED_WIKILINK_RE.exec(ref.trim());
- return match === null ? ref : match[1]!.trim();
-}
+export type OwnerScopeRef = ArtifactRef;
-/** The visibility decision, bound to one vault and one scope. */
-export interface OwnerScopeView {
+/** The ownership decision, bound to one vault and one scope. */
+export interface OwnerScopeView extends ArtifactRefView {
/** The enforced scope, or `null` when no ownership filtering applies. */
readonly scope: string | null;
- /** May the caller see the artifact or page this reference names? */
- readonly visible: (ref: OwnerScopeRef) => boolean;
- /**
- * May the caller see a row that names ALL of these? One hidden
- * reference hides the row: a row survives only when every artifact it
- * would disclose is one the caller may already see.
- */
- readonly row: (...refs: ReadonlyArray<OwnerScopeRef>) => boolean;
- /** Drop the rows whose references are not all visible. */
- readonly keep: <T>(
- rows: ReadonlyArray<T>,
- refsOf: (row: T) => ReadonlyArray<OwnerScopeRef>,
- ) => ReadonlyArray<T>;
-}
-
-/** A view that hides nothing, allocated once. */
-const UNFILTERED: OwnerScopeView = Object.freeze({
- scope: null,
- visible: () => true,
- row: () => true,
- keep: <T>(rows: ReadonlyArray<T>) => rows,
-});
-
-/**
- * Resolve a bare Brain artifact id to its vault-relative path, or `null`
- * when no artifact of that id is on disk.
- *
- * ## Why the directory list is the whole boundary
- *
- * `visible()` reads an id that resolves to no file as "this row names
- * nothing that could be owned" and lets the row through. That reading is
- * true only for ids this function would have FOUND had the artifact
- * existed - so every directory omitted here is a directory whose pages
- * are silently unownable, and the module's fail-closed promise turns
- * into a fail-open one for exactly those pages. The list is therefore
- * every `Brain/` directory holding id-addressable Markdown:
- *
- * - `preferences` / `retired` carry `owner:` through the preference
- * writer;
- * - `inbox` / `processed` / `pending` carry whatever an operator or an
- * importer wrote into a signal's frontmatter;
- * - `sources` (`src-<slug>.md`) and `entities` are owner-taggable the
- * same way, and `brain_search_by_source` already filters the first
- * of them by owner on the search side - so an id-shaped reference to
- * one reaching THIS view and passing was the two halves disagreeing.
- *
- * `log` is deliberately absent - a log shard is named by date, is shared
- * by construction, and has no owner to read. `bases` holds `.base` view
- * definitions rather than Markdown pages, and `snapshots` holds dated
- * copies addressed by path rather than by id.
- */
-function artifactPath(vault: string, id: string): string | null {
- const dirs = brainDirs(vault);
- for (const dir of [
- dirs.preferences,
- dirs.retired,
- dirs.inbox,
- dirs.processed,
- dirs.pending,
- join(vault, BRAIN_SOURCES_REL),
- dirs.entities,
- ]) {
- const abs = join(dir, `${id}${MARKDOWN_EXT}`);
- if (existsSync(abs)) return abs.slice(vault.length + 1);
- }
- return null;
}
/**
@@ -184,29 +88,10 @@ function artifactPath(vault: string, id: string): string | null {
* never opted in.
*/
export function ownerScopeView(vault: string, scope: string | null): OwnerScopeView {
- if (scope === null) return UNFILTERED;
- // One frontmatter read per (vault, path) for the whole response, the
- // same sharing `search()` gives its filter stages.
- const cache: FrontmatterCache = new Map();
- const visible = (ref: OwnerScopeRef): boolean => {
- if (ref === null || ref === undefined || ref.length === 0) return true;
- // A reference that names a path is resolved as one; anything else is
- // a Brain artifact id, and an id with no artifact on disk names
- // nothing that could be owned - see {@link artifactPath} for why
- // that reading is only true while its directory list is complete.
- const bare = unbracket(ref);
- if (bare.length === 0) return true;
- const rel = bare.endsWith(MARKDOWN_EXT) ? bare : artifactPath(vault, bare);
- if (rel === null) return true;
- return isPathOwnerVisible(vault, rel, scope, cache);
- };
- const row = (...refs: ReadonlyArray<OwnerScopeRef>): boolean => refs.every(visible);
+ if (scope === null) return Object.freeze({ scope: null, ...UNFILTERED_ARTIFACT_REFS });
return Object.freeze({
scope,
- visible,
- row,
- keep: <T>(rows: ReadonlyArray<T>, refsOf: (r: T) => ReadonlyArray<OwnerScopeRef>) =>
- rows.filter((r) => refsOf(r).every(visible)),
+ ...artifactRefView(vault, (rel, cache) => isPathOwnerVisible(vault, rel, scope, cache)),
});
}
diff --git a/src/core/brain/portability/graph.ts b/src/core/brain/portability/graph.ts
index 98ea5308..c0c16adf 100644
--- a/src/core/brain/portability/graph.ts
+++ b/src/core/brain/portability/graph.ts
@@ -35,6 +35,7 @@ import { REDACTION_PLACEHOLDER } from "../../redactor.ts";
import { BRAIN_ROOT_REL, ensureInsideVault } from "../paths.ts";
import { loadVaultMap, resolveTokens } from "./role-tokens.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
export const GRAPH_VERSION = "1";
@@ -84,7 +85,10 @@ function collectRelations(meta: FrontmatterMap): Record<string, ReadonlyArray<st
* sorted graph. Pure and read-only.
*/
export function exportVaultGraph(vault: string): VaultGraph {
- const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL] });
+ const pages = listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
+ reach: MAINTENANCE_LANE_REACH,
+ });
const nodes: VaultGraphNode[] = [];
for (const page of pages) {
let body: string;
diff --git a/src/core/brain/portability/page-contract.ts b/src/core/brain/portability/page-contract.ts
index 41fba724..5ce7b47a 100644
--- a/src/core/brain/portability/page-contract.ts
+++ b/src/core/brain/portability/page-contract.ts
@@ -26,6 +26,7 @@ import {
} from "../../graph/frontmatter-relations.ts";
import { BRAIN_ROOT_REL } from "../paths.ts";
import { isoSecond } from "../time.ts";
+import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";
export const PAGE_CONTRACT_VERSION = "1";
@@ -109,7 +110,10 @@ function freshnessOf(meta: FrontmatterMap, absPath: string): string | null {
* `path` for deterministic output. Pure and read-only.
*/
export function projectPageContracts(vault: string): ReadonlyArray<PageContract> {
- const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL] });
+ const pages = listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
+ reach: MAINTENANCE_LANE_REACH,
+ });
const contracts: PageContract[] = [];
for (const page of pages) {
let body: string;
diff --git a/src/core/brain/query.ts b/src/core/brain/query.ts
index bb4c34cd..5874df02 100644
--- a/src/core/brain/query.ts
+++ b/src/core/brain/query.ts
@@ -34,7 +34,10 @@ import { filterExpired, isExpired } from "./expiration.ts";
import type { BrainLogEntry } from "./log.ts";
import { listLogDates, readLogDay } from "./log-jsonl.ts";
import { parsePreference, parseRetired } from "./preference.ts";
-import { ownerScopeView, type OwnerScopeView } from "./owner-scope-view.ts";
+import { ownerScopeView } from "./owner-scope-view.ts";
+import { everyArtifactRefView, type ArtifactRefView } from "./artifact-ref-view.ts";
+import { reachView } from "./reach-view.ts";
+import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { parseSignal } from "./signal.ts";
import { isTombstoned } from "./lifecycle/tombstone.ts";
import { parseFrontmatter } from "../vault.ts";
@@ -127,6 +130,18 @@ export interface QueryByTopicOptions {
* rule this caller actually has.
*/
readonly ownerScope?: string | null;
+ /**
+ * Transport reach the topic's CURRENT RULE is selected under
+ * (private-is-not-a-suggestion, unit 5). Absent resolves to the
+ * narrowest.
+ *
+ * It reaches the SELECTION for the same reason the owner scope above
+ * does: a topic resolves to exactly one preference, so filtering the
+ * result afterwards would report the topic as having no rule at all
+ * whenever a reserved preference happened to sort ahead of a readable
+ * one - hiding the readable rule from every caller.
+ */
+ readonly transportReach?: TransportReach;
}
// ----- Public API -----------------------------------------------------------
@@ -249,7 +264,13 @@ export function queryByTopic(
signals = filterExpired(signals, { now, showExpired });
// Current rule β€” prefer the active preference; fall back to retired.
- const view = ownerScopeView(vault, options.ownerScope ?? null);
+ // Both selection rules, ANDed. They are independent questions and
+ // neither is folded into the other; a candidate survives the walk only
+ // when both keep it.
+ const view = everyArtifactRefView(
+ ownerScopeView(vault, options.ownerScope ?? null),
+ reachView(vault, resolvedTransportReach(options.transportReach)),
+ );
let preference: BrainPreference | BrainRetired | null = null;
preference = findPreferenceForTopic(dirs.preferences, want, "preference", view);
if (!preference) {
@@ -372,7 +393,7 @@ function findPreferenceForTopic(
dir: string,
topic: string,
kind: "preference" | "retired",
- view: OwnerScopeView,
+ view: ArtifactRefView,
): BrainPreference | BrainRetired | null {
if (!existsSync(dir)) return null;
const prefix = kind === "preference" ? "pref-" : "ret-";
diff --git a/src/core/brain/reach-view.ts b/src/core/brain/reach-view.ts
new file mode 100644
index 00000000..f117183c
--- /dev/null
+++ b/src/core/brain/reach-view.ts
@@ -0,0 +1,48 @@
+/**
+ * What a caller at one transport reach may see, over the REFERENCES a
+ * report row carries.
+ *
+ * The visibility half of the pair `./owner-scope-view.ts` opens. Both
+ * bind one per-path rule to `./artifact-ref-view.ts`'s reference grammar;
+ * the rules themselves are independent and neither is folded into the
+ * other. A row survives a surface only if BOTH views keep it, and the
+ * order they are asked in is not observable, because a hidden row is
+ * dropped rather than reported by either.
+ *
+ * Unlike the owner view, this one is NOT gated on operator configuration.
+ * `gatedOwnerScopeView` is inert unless `integrity.owner_scope_delivery`
+ * is `fail`; a boundary an operator must switch on is the defect this
+ * wave exists to remove, so the reach view is always live and its
+ * escape hatch is the transport the caller arrived on.
+ */
+
+import { TRANSPORT_REACH, type TransportReach } from "../graph/transport-reach.ts";
+import { isPathReadableAtReach } from "../search/result-filters.ts";
+import {
+ UNFILTERED_ARTIFACT_REFS,
+ artifactRefView,
+ type ArtifactRefView,
+} from "./artifact-ref-view.ts";
+
+/** The reserved-token decision, bound to one vault and one reach. */
+export interface ReachView extends ArtifactRefView {
+ /** The reach this view answers for. */
+ readonly reach: TransportReach;
+}
+
+/**
+ * Bind the reserved-token rule to one vault and one reach.
+ *
+ * {@link TRANSPORT_REACH.local} returns the shared no-op view, so the
+ * transports that establish local access pay one comparison per call and
+ * read nothing - the same shape `ownerScopeView` uses for an unset scope.
+ */
+export function reachView(vault: string, reach: TransportReach): ReachView {
+ if (reach === TRANSPORT_REACH.local) {
+ return Object.freeze({ reach, ...UNFILTERED_ARTIFACT_REFS });
+ }
+ return Object.freeze({
+ reach,
+ ...artifactRefView(vault, (rel, cache) => isPathReadableAtReach(vault, rel, reach, cache)),
+ });
+}
diff --git a/src/core/brain/schema-report.ts b/src/core/brain/schema-report.ts
index bb55f251..40445274 100644
--- a/src/core/brain/schema-report.ts
+++ b/src/core/brain/schema-report.ts
@@ -15,6 +15,7 @@ import {
type SchemaVocabularyCategory,
} from "./schema-vocab.ts";
import { parseSignal } from "./signal.ts";
+import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";
export interface SchemaTokenUsage {
readonly token: string;
@@ -234,7 +235,7 @@ function scanPageTypes(
counts: Map<string, number>,
findings: SchemaReportFinding[],
): void {
- for (const page of listVaultPages(vault)) {
+ for (const page of listVaultPages(vault, { reach: MAINTENANCE_LANE_REACH })) {
const rel = vaultRelative(page.path, vault);
if (rel === "Brain" || rel.startsWith("Brain/")) continue;
const raw = page.metadata["schema_type"];
diff --git a/src/core/brain/skill-page-drafts.ts b/src/core/brain/skill-page-drafts.ts
index e7720306..cdc11921 100644
--- a/src/core/brain/skill-page-drafts.ts
+++ b/src/core/brain/skill-page-drafts.ts
@@ -71,6 +71,7 @@ import {
type DeclaredSkillProposalResult,
} from "./skill-proposals.ts";
import { BRAIN_CONFIDENCE } from "./types.ts";
+import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";
/** Lowest tier a page may carry and still be a skill candidate. */
export const MATURE_PAGE_TIER: PageTier = PAGE_TIER.core;
@@ -225,7 +226,10 @@ export function planSkillPageDrafts(
opts: PlanSkillPageDraftsOptions,
): SkillPageDraftPlan {
const brainDir = BRAIN_ROOT_REL.split("/")[0] ?? "Brain";
- const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, brainDir] });
+ const pages = listVaultPages(vault, {
+ skipDirs: [...EXCLUDED_DIRS, brainDir],
+ reach: MAINTENANCE_LANE_REACH,
+ });
const reuse = observedReuseRates(vault);
const covered = installedSkillNames(vault, opts);
diff --git a/src/core/brain/wikilink.ts b/src/core/brain/wikilink.ts
index 4ec91592..3e1a8800 100644
--- a/src/core/brain/wikilink.ts
+++ b/src/core/brain/wikilink.ts
@@ -107,12 +107,28 @@ export function normaliseWikilinkTarget(value: string): string {
* {@link parseArtifactRef} β€” they apply the same Obsidian-flavoured
* resolution rules to the post-bracket part of the link.
*/
-function stripBasenameDecoration(body: string): string {
+/**
+ * Drop a wikilink body's alias and anchor, keeping the target verbatim -
+ * folder segments and `.md` included.
+ *
+ * The half of {@link stripBasenameDecoration} that removes DECORATION,
+ * split out because a consumer that resolves a target to a vault path
+ * needs exactly this and must not have the other half: collapsing
+ * `Brain/preferences/pref-x.md|the rule` to `pref-x` turns a
+ * path-shaped reference into a bare basename that resolves to no file,
+ * which is a fail-open for any rule asked over it.
+ */
+export function stripWikilinkDecoration(body: string): string {
let s = body.trim();
const pipe = s.indexOf("|");
if (pipe >= 0) s = s.slice(0, pipe).trim();
const hash = s.indexOf("#");
if (hash >= 0) s = s.slice(0, hash).trim();
+ return s;
+}
+
+function stripBasenameDecoration(body: string): string {
+ let s = stripWikilinkDecoration(body);
s = basename(s);
if (s.endsWith(".md")) s = s.slice(0, -".md".length);
return s;
diff --git a/src/core/graph/transport-reach.ts b/src/core/graph/transport-reach.ts
new file mode 100644
index 00000000..82aa5646
--- /dev/null
+++ b/src/core/graph/transport-reach.ts
@@ -0,0 +1,97 @@
+/**
+ * How far the caller of this process had to reach to get here.
+ *
+ * A vault page may reserve itself against remote reads (see
+ * {@link REMOTE_DENY_VISIBILITY_TOKEN} in `./visibility.ts`). Deciding
+ * whether a given read is such a read needs one fact, and the only party
+ * that holds it is the TRANSPORT: stdio and the CLI run inside a process
+ * the caller already started on this host, while an HTTP request arrives
+ * from wherever it arrives from.
+ *
+ * So the value is MINTED by each transport constructor and never parsed
+ * out of a request. A caller-supplied trust claim is not a trust claim -
+ * the rule `src/mcp/owner-scope-refusal.ts` states once for owner
+ * identity, applied here to reach - which is why a reach-shaped member in
+ * a tool's arguments is refused by name rather than read.
+ *
+ * What each member actually proves, stated plainly rather than
+ * overclaimed:
+ *
+ * - `local` - the caller already holds filesystem-equivalent access to
+ * this vault (stdio and the CLI run as a child of the caller), or the
+ * request originated on this host (a loopback HTTP bind). It does NOT
+ * prove operator intent: a remote host can spawn a stdio subprocess.
+ * The alternative - no bypass at all - would take an operator's own
+ * private notes away from their own CLI, so the bypass exists and its
+ * limit is written down here.
+ * - `remote` - nothing beyond "a request arrived". This is the default
+ * for every non-loopback bind, and the reach a page reserving itself
+ * against remote reads is reserved against.
+ *
+ * Naming: `disclosure` was the design's word for this, and it is already
+ * taken in this tree - `SearchOptions.disclosure` is the progressive
+ * result-DEPTH mode (`full` | `cards`). Two fields called `disclosure` on
+ * one options bag, meaning different things, is the "one rule, two
+ * spellings" defect this suite exists to remove, so the transport fact is
+ * named for what it measures instead.
+ */
+
+/** The closed vocabulary. See the module docblock for what each proves. */
+export const TRANSPORT_REACH = Object.freeze({
+ /** Filesystem-equivalent access, or a request from this host. */
+ local: "local",
+ /** A request arrived, and nothing further is established. */
+ remote: "remote",
+} as const);
+
+/** Closed union over {@link TRANSPORT_REACH}. */
+export type TransportReach = (typeof TRANSPORT_REACH)[keyof typeof TRANSPORT_REACH];
+
+/** Membership list, widest-access-first. */
+export const TRANSPORT_REACHES: ReadonlyArray<TransportReach> = Object.freeze([
+ TRANSPORT_REACH.local,
+ TRANSPORT_REACH.remote,
+]);
+
+/**
+ * Narrow a reach read back off a stored envelope or a test fixture.
+ *
+ * Deliberately NOT used to accept one from a request - see the module
+ * docblock for why a reach arriving from a caller is refused instead.
+ */
+export function isTransportReach(value: unknown): value is TransportReach {
+ return typeof value === "string" && (TRANSPORT_REACHES as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * The reach to answer at when nobody minted one.
+ *
+ * An unestablished reach is not the absence of a boundary, so an absent
+ * value resolves to {@link TRANSPORT_REACH.remote}, the narrowest. Named
+ * here once because the alternative is what it was: the same `?? remote`
+ * spelled at every options bag and every context reader, which is one
+ * rule with six spellings and five places to forget to change it.
+ *
+ * Callers that hold a `ServerContext` reach it through `contextReach`
+ * (`src/mcp/tool-contract.ts`), which is this function under the name
+ * that seam already uses.
+ */
+export function resolvedTransportReach(reach: TransportReach | undefined): TransportReach {
+ return reach ?? TRANSPORT_REACH.remote;
+}
+
+/**
+ * The reach an INTERNAL maintenance lane walks the vault at.
+ *
+ * `local`, and not because a lane proved anything about a caller - it has
+ * no caller. A heal pass, a link-graph repair, a portability export, a
+ * freshness sweep or a schema report reads the vault to reason about the
+ * vault, and its output is a repair or a diagnostic rather than a page
+ * handed to anyone. A lane that stopped seeing reserved pages would
+ * report a smaller vault than the one it is fixing, and would then break
+ * the links into the pages it could not see.
+ *
+ * Named here once so the claim every lane makes is the same claim, and so
+ * a reader can find all of them by finding this constant.
+ */
+export const MAINTENANCE_LANE_REACH: TransportReach = TRANSPORT_REACH.local;
diff --git a/src/core/graph/visibility.ts b/src/core/graph/visibility.ts
index 43dcca06..3dfae701 100644
--- a/src/core/graph/visibility.ts
+++ b/src/core/graph/visibility.ts
@@ -15,8 +15,16 @@
* Visibility values are opaque, language-neutral tokens (e.g. `private`,
* `team`, `agent:foo`); nothing here hardcodes a natural-language
* phrase or a closed enum.
+ *
+ * ONE of those tokens is additionally RESERVED - see
+ * {@link REMOTE_DENY_VISIBILITY_TOKEN} - as a controlled-vocabulary
+ * identifier meaning "not readable at remote reach". That is a second,
+ * independent question from the caller-scope rule above, answered by
+ * {@link isRemotelyReadable}, and the two compose: the caller's scope may
+ * only ever NARROW, and can no longer lift the reserved token.
*/
+import { TRANSPORT_REACH, type TransportReach } from "./transport-reach.ts";
import type { FrontmatterMap } from "../types.ts";
/** Lower-case + NFC + trim a single visibility token. */
@@ -55,3 +63,41 @@ export function isVisible(pageTags: ReadonlyArray<string>, scope: ReadonlySet<st
for (const t of pageTags) if (scope.has(t)) return true;
return false;
}
+
+/**
+ * The one visibility token that denies a remote read.
+ *
+ * A vocabulary identifier, in the same sense as `kind: entity` or an
+ * entity `status` value - not a natural-language phrase, and not the head
+ * of a list of translations. It is written here once, already in the
+ * normal form {@link normToken} produces, so a page cannot spell it a
+ * second way and mean something else.
+ *
+ * Every OTHER token, reserved-adjacent or not, keeps exactly the
+ * caller-liftable semantics {@link isVisible} gives it: this constant
+ * reserves one identifier and defines no policy for any other.
+ */
+export const REMOTE_DENY_VISIBILITY_TOKEN = "private";
+
+/**
+ * May a caller that reached this process at `reach` read a page carrying
+ * `pageTags`?
+ *
+ * Deny by default at {@link TRANSPORT_REACH.remote} for the reserved
+ * token, and nothing else: an untagged page, and a page carrying only
+ * non-reserved tokens, answer `true` at every reach and are left entirely
+ * to {@link isVisible}. A vault that never wrote the reserved token
+ * therefore sees no change from this predicate at all.
+ *
+ * `pageTags` must come from {@link pageVisibility}, which is where the
+ * normalisation happens; passing raw frontmatter strings would compare an
+ * un-normalised token against a normalised constant and silently admit a
+ * page that declared the reserved token in another case.
+ */
+export function isRemotelyReadable(
+ pageTags: ReadonlyArray<string>,
+ reach: TransportReach,
+): boolean {
+ if (reach === TRANSPORT_REACH.local) return true;
+ return !pageTags.includes(REMOTE_DENY_VISIBILITY_TOKEN);
+}
diff --git a/src/core/search/benchmark.ts b/src/core/search/benchmark.ts
index 9d7e4b08..a792d7e1 100644
--- a/src/core/search/benchmark.ts
+++ b/src/core/search/benchmark.ts
@@ -21,6 +21,7 @@
import { Semaphore } from "./embeddings/http-util.ts";
import { search } from "./search.ts";
+import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { SearchError } from "./types.ts";
import type { ResolvedSearchConfig, SearchOutcome } from "./types.ts";
@@ -81,6 +82,26 @@ export interface RecallBenchmarkOptions {
readonly k?: number;
/** Route every query through deterministic expansion (t_2fa95db1). */
readonly expand?: boolean;
+ /**
+ * The reach the party that supplied this dataset was established at.
+ *
+ * Load-bearing, not decorative. This is not an internal lane: the
+ * dataset is a required argument of `brain_benchmark` and `brain_tune`,
+ * both callable over any transport, and the report answers per query
+ * with `hit`, `rank`, `expectedFound` for caller-named paths and
+ * `answerContained` for a caller-supplied string. Run at a reach the
+ * caller did not earn, that is an existence oracle over the reserved
+ * corpus and a substring oracle over its bodies - reachable without
+ * ever calling a tool the registry classifies as covered.
+ *
+ * Absent resolves to the narrowest, on the same terms
+ * {@link SearchOptions.transportReach} does. The lanes that must score
+ * the whole corpus - the CLI benchmark, the tuning sweep's own
+ * measurement, the rerank eval gate - pass {@link TRANSPORT_REACH.local}
+ * explicitly, because a benchmark that stopped seeing reserved pages
+ * would score a smaller corpus than the one it is benchmarking.
+ */
+ readonly transportReach?: TransportReach;
}
export interface RecallBenchmarkQueryResult {
@@ -230,6 +251,7 @@ export async function runRecallBenchmark(
}
const k = opts.k ?? BENCHMARK_DEFAULT_K;
const expand = opts.expand === true;
+ const reach = resolvedTransportReach(opts.transportReach);
const perQuery = await Promise.all(
dataset.queries.map(async (q): Promise<RecallBenchmarkQueryResult> => {
@@ -241,6 +263,10 @@ export async function runRecallBenchmark(
query: q.query,
limit: depth,
...(expand ? { expand: true } : {}),
+ // The reach of whoever supplied the dataset - see
+ // `RecallBenchmarkOptions.transportReach` for why this is not
+ // the internal-lane constant it used to be.
+ transportReach: reach,
});
} finally {
permit();
diff --git a/src/core/search/cards.ts b/src/core/search/cards.ts
index 8d4afb32..21458eb7 100644
--- a/src/core/search/cards.ts
+++ b/src/core/search/cards.ts
@@ -6,7 +6,8 @@
import { normalizeAgentScope } from "../graph/agent-scope.ts";
import { formatLinePointer } from "./line-numbering.ts";
-import { isPathOwnerVisible } from "./result-filters.ts";
+import { isPathOwnerVisible, isPathReadableAtReach } from "./result-filters.ts";
+import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { markWindow, matchOffset, toCodePointOffset, windowStartWithin } from "./snippet-window.ts";
import { Store } from "./store.ts";
import { SearchError } from "./types.ts";
@@ -150,6 +151,7 @@ export async function expandHit(
throw new SearchError("INVALID_INPUT", "chunkId must be a positive integer");
}
const agentScope = normalizeAgentScope(input.agentScope);
+ const reach = resolvedTransportReach(input.transportReach);
const store = await Store.open(config, { mode: "read" });
try {
const hit = store.hydrateChunks([input.chunkId]).get(input.chunkId);
@@ -159,6 +161,9 @@ export async function expandHit(
if (agentScope !== null && !ownerVisible(config, hit.path, agentScope)) {
throw notFound(input.chunkId);
}
+ if (!reachReadable(config, hit.path, reach)) {
+ throw notFound(input.chunkId);
+ }
// Document chunks in `chunkIndex` order: the fuller note (layer 2) is
// their concatenation; the raw transcript (layer 3) is the same rows.
const chunks = store.getChunksByDocument(hit.documentId);
@@ -207,6 +212,21 @@ function notFound(chunkId: number): SearchError {
return new SearchError("INVALID_INPUT", `chunk not found: ${chunkId}`);
}
+/**
+ * May a caller at `reach` read the note at `path`? Fails CLOSED on an
+ * unreadable page, exactly as the ranked filter decides it.
+ *
+ * Delegates to {@link isPathReadableAtReach} rather than restating the
+ * rule, so the drill-down and the ranked pipeline cannot drift on what
+ * "reserved" means. Unlike the ownership check above, this one is asked
+ * on EVERY call rather than only when the caller supplied an argument -
+ * the reach is never a caller argument, and a boundary a caller opts into
+ * is not a boundary.
+ */
+function reachReadable(config: ResolvedSearchConfig, path: string, reach: TransportReach): boolean {
+ return isPathReadableAtReach(config.vault, path, reach, new Map());
+}
+
/**
* Is the note at `path` reachable under `scope`? Fails CLOSED on an
* unreadable page, matching `applyAgentScope` on the ranked path: an
diff --git a/src/core/search/feedback.ts b/src/core/search/feedback.ts
index 1aafbc7b..4c58321e 100644
--- a/src/core/search/feedback.ts
+++ b/src/core/search/feedback.ts
@@ -24,6 +24,7 @@ import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync
import { join } from "node:path";
import type { BrainSearchResult, ResolvedSearchConfig, WeightProfile } from "./types.ts";
+import type { TransportReach } from "../graph/transport-reach.ts";
/** Lower bound for one learned per-layer multiplier. */
export const LEARNED_WEIGHT_MIN = 0.8;
@@ -282,12 +283,29 @@ export function learnedWeightsReason(w: WeightProfile): string {
return `learned_weights: ${parts.join(" ")}`;
}
+/**
+ * How deep the judged query is re-run before the verdict is scored.
+ * Hoisted so the depth is named where it is decided rather than inline.
+ */
+const FEEDBACK_RERUN_LIMIT = 50;
+
export interface CaptureRecallFeedbackInput {
readonly query: string;
readonly resultPath: string;
readonly verdict: "up" | "down";
/** Injected clock for deterministic tests. Defaults to Date.now(). */
readonly nowMs?: number;
+ /**
+ * How far this caller reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`).
+ *
+ * Load-bearing rather than decorative: {@link
+ * CaptureRecallFeedbackOutcome.resultFound} reports whether the judged
+ * path came back, so a re-run that saw a reserved page would answer
+ * "yes, it exists" to a caller the page is reserved against. Omitted
+ * resolves to the narrowest.
+ */
+ readonly transportReach?: TransportReach;
}
export interface CaptureRecallFeedbackOutcome {
@@ -312,7 +330,11 @@ export async function captureRecallFeedback(
input: CaptureRecallFeedbackInput,
): Promise<CaptureRecallFeedbackOutcome> {
const { search } = await import("./search.ts");
- const outcome = await search(config, { query: input.query, limit: 50 });
+ const outcome = await search(config, {
+ query: input.query,
+ limit: FEEDBACK_RERUN_LIMIT,
+ ...(input.transportReach !== undefined ? { transportReach: input.transportReach } : {}),
+ });
const hit = outcome.results.find((r) => r.path === input.resultPath);
const contributions: LayerContributions = hit
? contributionsFromResult(hit)
diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.ts
index 09b3ee4a..ee1f6a3e 100644
--- a/src/core/search/indexer.ts
+++ b/src/core/search/indexer.ts
@@ -82,7 +82,7 @@ import {
formatEmbedderRecordContradiction,
formatEmbeddingAbiDrift,
peekPendingVectorsSync,
- peekVisibilityTagPresence,
+ peekVisibilityColumnCensus,
readEmbedderRecordCensusSync,
readEmbeddingAbiSync,
runtimeEmbeddingAbi,
@@ -110,6 +110,7 @@ import type {
ResolvedSearchConfig,
VisibilityHonestyFinding,
} from "./types.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN, pageVisibility } from "../graph/visibility.ts";
// ─────────────────────────────────────────────────────────────────────────────
@@ -461,6 +462,13 @@ async function indexIntoRun(
// above: unchanged content can only ever resolve to the same
// anchor, so declining to recompute it cannot stale it.
eventAnchor: resolveEventAnchor(frontmatter, body),
+ // What this run MEASURED of the page's visibility declaration,
+ // from the frontmatter already parsed above (v12). The indexer
+ // marks; it never skips. A `continue` here would be a live
+ // defect: `seen.add` runs BEFORE the content is read, so the
+ // deletion sweep would not purge a skipped page's stale rows and
+ // the page would keep whatever chunks it already had.
+ visibility: pageVisibility(frontmatter),
});
// Framework-kind files feed the tier-guard post-pass: keep the
// parsed frontmatter of this run's changed docs that declare a
@@ -1656,9 +1664,9 @@ function readPendingVectorCensus(dbPath: string): PendingVectorCensus {
* The visibility honesty finding for an index path, or `null` when there
* is nothing to be honest ABOUT: the index does not exist, would not
* open, or - the common case - has never carried a `visibility:`-tagged
- * page. Both counts are read off the registry's own exported list at
- * call time, never hand-written, so the finding cannot drift from the
- * census that backs it (nothing-writes-silently, unit H, form B).
+ * page AND measured every document it holds. The surface counts are read off the registry's own exported list
+ * at call time and the document counts off the index's own column, never
+ * hand-written, so the finding cannot drift from what backs it.
*
* CALLABLE rows only. The registry also carries one `index_store` row -
* the fact that `chunks` stores a private page's text whatever a
@@ -1666,11 +1674,23 @@ function readPendingVectorCensus(dbPath: string): PendingVectorCensus {
* operator could call would inflate a number reported to operators.
*/
function readVisibilityHonestyFinding(dbPath: string): VisibilityHonestyFinding | null {
- const peek = peekVisibilityTagPresence(dbPath);
- if (peek.kind !== "read" || !peek.value) return null;
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
+ if (peek.kind !== "read") return null;
+ // Reported when the index HAS something to be honest about, which is
+ // either a tagged page or a population it could not measure. Gating on
+ // `tagged` alone suppressed the unmeasured count in exactly the state
+ // it exists to surface: an index migrated to v12 whose chunk-zero rows
+ // are gone reads as untagged for every row, so the operator was told
+ // nothing at all about the documents the index measured nothing for.
+ if (!peek.value.tagged && peek.value.unmeasured === 0) return null;
return Object.freeze({
excludedSurfaceCount: excludedCallableVisibilitySurfaces().length,
totalSurfaceCount: callableVisibilitySurfaces().length,
+ // Both from the store, never hand-written, for the same reason the
+ // two surface counts are read off the registry: a number an operator
+ // acts on must be the measurement rather than a copy of one.
+ reservedDocumentCount: peek.value.reserved,
+ unmeasuredDocumentCount: peek.value.unmeasured,
});
}
diff --git a/src/core/search/pipeline/assemble.ts b/src/core/search/pipeline/assemble.ts
index 30f5bfea..3e4fd5ca 100644
--- a/src/core/search/pipeline/assemble.ts
+++ b/src/core/search/pipeline/assemble.ts
@@ -96,6 +96,7 @@ export interface AssemblyInput {
interface Assembly {
readonly preVisibility: number;
+ readonly prePoolFilters: number;
readonly visible: ReadonlyArray<BrainSearchResult>;
/** Whether the cap truncated the pool, as opposed to the pool running out. */
readonly capHit: boolean;
@@ -326,8 +327,9 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
// candidate list:
//
// - default-scope visibility (no explicit filter, so no overfetch
- // above) drops tagged pages; untagged vaults never drop a row, so
- // this never fires for them,
+ // above) drops tagged pages, and the reserved-token rule drops pages
+ // reserved against this caller's reach; untagged vaults never drop a
+ // row, so this never fires for them,
// - the exact-duplicate merge folds byte-identical passages away.
//
// In either case, and only when the narrow cap was actually hit (as
@@ -336,7 +338,7 @@ export function assembleRankedResults(input: AssemblyInput): ReadonlyArray<Brain
// fetch. A pool with no dropped and no merged rows never re-assembles,
// so its results stay byte-identical.
const visibilityDropped =
- !filters.canDropRows && assembled.visible.length < assembled.preVisibility;
+ !filters.canDropRows && assembled.visible.length < assembled.prePoolFilters;
if (
assembled.visible.length < limit &&
assembled.capHit &&
@@ -375,9 +377,12 @@ function noteAssemblyNarrowings(
dropped: assembled.floorDropped,
});
}
- // `preVisibility` is the row count before visibility, ownership and the
- // composite session/project scope ran. The difference is the answer to
- // "did a scope remove my results", which nothing could ask before.
+ // `preVisibility` is the row count before the visibility, ownership and
+ // composite session/project scopes the CALLER requested ran - the reach
+ // rule is already counted out of it. The difference is the answer to
+ // "did a scope remove my results", which nothing could ask before; the
+ // reach rule is not one of those scopes, and its drop count is withheld
+ // rather than published (see `pipeline/pool-filters.ts`).
const scoped = assembled.preVisibility - assembled.visible.length;
if (scoped > 0) {
noteDegradation(sink, RETRIEVAL_DEGRADATION.scopeFiltersDroppedRows, {
diff --git a/src/core/search/pipeline/pool-filters.ts b/src/core/search/pipeline/pool-filters.ts
index 5c3a4078..397e50f4 100644
--- a/src/core/search/pipeline/pool-filters.ts
+++ b/src/core/search/pipeline/pool-filters.ts
@@ -9,6 +9,7 @@
import { normalizeAgentScope } from "../../graph/agent-scope.ts";
import { normalizeVisibilityScope } from "../../graph/visibility.ts";
+import { resolvedTransportReach, type TransportReach } from "../../graph/transport-reach.ts";
import { normalizeScopeFilter } from "../../scope-key.ts";
import {
applyAgentScope,
@@ -16,6 +17,7 @@ import {
applyPropertyFilter,
applyScopeFilter,
applyStatusFilter,
+ applyReachFilter,
applyVisibilityScope,
type FrontmatterCache,
} from "../result-filters.ts";
@@ -27,6 +29,12 @@ export interface PoolFilters {
readonly properties: ReadonlyMap<string, ReadonlyArray<string>> | null;
readonly degreeFilters: ReadonlyArray<DegreePredicate>;
readonly visibilityScope: ReturnType<typeof normalizeVisibilityScope>;
+ /**
+ * The reach this search's caller was established at. Absent from the
+ * options means nobody established one, which resolves to the narrowest
+ * - see {@link SearchOptions.transportReach}.
+ */
+ readonly reach: TransportReach;
readonly agentScope: ReturnType<typeof normalizeAgentScope>;
readonly scopeFilter: ReturnType<typeof normalizeScopeFilter> | null;
/**
@@ -57,6 +65,13 @@ export function resolvePoolFilters(opts: SearchOptions): PoolFilters {
// the window.
const visibilityScope = normalizeVisibilityScope(opts.visibility ?? []);
const hasVisibilityRequest = (opts.visibility?.length ?? 0) > 0;
+ // Deny-by-default reach. NOT folded into `canDropRows`: a reserved page
+ // dropped at remote reach shrinks the window exactly the way a tagged
+ // page already does under the default scope, and the assembly's
+ // one-shot backfill is what widens the pool when it actually happens.
+ // Folding it in would make every remote search overfetch up front,
+ // including in the vaults that never wrote the token.
+ const reach = resolvedTransportReach(opts.transportReach);
// Agent-ownership scope (Unit 5): null means "no scope requested" -
// no ownership filtering, so untagged vaults stay byte-identical.
const agentScope = normalizeAgentScope(opts.agentScope);
@@ -73,6 +88,7 @@ export function resolvePoolFilters(opts: SearchOptions): PoolFilters {
properties,
degreeFilters,
visibilityScope,
+ reach,
agentScope,
scopeFilter,
canDropRows:
@@ -92,13 +108,32 @@ export interface FilterContext {
export interface FilteredPool {
/**
- * Row count before visibility scoping, for the backfill decision - and,
- * since evidence-at-the-boundary C2, for the retrieval trail: the gap
- * between this and `visible` is the only evidence that an owner,
- * visibility or session scope removed the answer rather than the vault
- * holding no match.
+ * Row count after the reach rule and before every CALLER-REQUESTED
+ * scope. Since evidence-at-the-boundary C2 this is the retrieval
+ * trail's baseline: the gap between it and `visible` is the only
+ * evidence that an owner, visibility or session scope removed the
+ * answer rather than the vault holding no match.
+ *
+ * The reserved-token rule is counted OUT of it. That rule is not a
+ * scope the caller requested, and publishing how many rows it removed
+ * would tell the caller that pages it may not read matched its query -
+ * which is the existence oracle the boundary exists to close. Use
+ * {@link FilteredPool.prePoolFilters} for anything that must see the
+ * whole drop and does not report it.
*/
readonly preVisibility: number;
+ /**
+ * Row count before ANY post-rank filter that can shrink the window,
+ * the reach rule included.
+ *
+ * Exists for the assembly's one-shot backfill, which has to widen the
+ * rank cap whenever the window shrank for a reason the caller did not
+ * ask for - and a reserved page crowding the cap is exactly that. It
+ * is deliberately NOT the trail's baseline: the backfill consumes this
+ * number to fetch more rows and never reports it, so it discloses
+ * nothing, while the trail publishes its baseline verbatim.
+ */
+ readonly prePoolFilters: number;
readonly visible: ReadonlyArray<BrainSearchResult>;
}
@@ -127,8 +162,20 @@ export function applyPoolFilters(
filters.degreeFilters.length > 0
? applyDegreeFilter(propFiltered, filters.degreeFilters, ctx.store)
: propFiltered;
- const visible = applyVisibilityScope(
+ // Root A, and it runs BEFORE the trail's baseline is taken. The
+ // caller's own scopes are counted below, because "did my scope remove
+ // my results" is a question the caller may ask about a filter it
+ // requested; the reserved-token rule is not one of those, and a count
+ // of what it withheld would say "there is one more page here than I am
+ // showing you" - the existence oracle the boundary exists to close.
+ const reachable = applyReachFilter(
degreeFiltered,
+ filters.reach,
+ ctx.vault,
+ ctx.frontmatterCache,
+ );
+ const visible = applyVisibilityScope(
+ reachable,
filters.visibilityScope,
ctx.vault,
ctx.frontmatterCache,
@@ -146,5 +193,14 @@ export function applyPoolFilters(
filters.scopeFilter !== null
? applyScopeFilter(scoped, filters.scopeFilter, ctx.vault, ctx.frontmatterCache)
: scoped;
- return { preVisibility: degreeFiltered.length, visible: compositeScoped };
+ // Two counts, and the split is the whole point: the trail subtracts
+ // from the pool AFTER the reach rule, so the number it publishes is
+ // exactly what the caller's own arguments removed, while the backfill
+ // subtracts from the pool BEFORE it, so a reserved page crowding the
+ // rank cap still widens the window rather than emptying it.
+ return {
+ preVisibility: reachable.length,
+ prePoolFilters: degreeFiltered.length,
+ visible: compositeScoped,
+ };
}
diff --git a/src/core/search/pipeline/post-rank.ts b/src/core/search/pipeline/post-rank.ts
index bb4a3833..528e5c69 100644
--- a/src/core/search/pipeline/post-rank.ts
+++ b/src/core/search/pipeline/post-rank.ts
@@ -15,10 +15,12 @@ import {
} from "../../brain/trust/retrieval-receipts.ts";
import { trustGateAdjuster } from "../../brain/trust/retrieval-gate.ts";
import { applyRelationPolarityPhase } from "../graph-phases.ts";
+import { resolvedTransportReach } from "../../graph/transport-reach.ts";
import { applyRankAdjusters, type RankAdjuster } from "../rank-adjust.ts";
import { applyReinforceBoost, loadReinforceStrengths } from "../reinforce.ts";
import { applyCrossEncoderRerank } from "../rerank/index.ts";
import {
+ applyReachFilter,
readCachedFrontmatter,
supersedeFadeAdjuster,
type FrontmatterCache,
@@ -67,6 +69,32 @@ export async function applyPostRankPhases(input: PostRankInput): Promise<PostRan
const polarized = config.recall.relationPolarityEnabled
? applyRelationPolarityPhase(store, excluded, opts.includeSuperseded === true)
: excluded;
+ // Root A again, and it has to be: the polarity phase resolves typed
+ // `superseded_by` edges to documents that were NEVER in the filtered
+ // pool, fetches their representative chunks off the store and appends
+ // them with full path, title and content. Nothing between that append
+ // and the outcome re-asks any pool filter, so a public page naming a
+ // reserved successor was a route to that successor's body at remote
+ // reach - the pool filter never saw it, because it was not in the pool
+ // to see. Re-asking over the whole pool rather than the pulled-in rows
+ // alone is deliberate: the verdict is idempotent and every already-
+ // filtered row answers off the shared frontmatter cache, so one
+ // spelling of the rule costs less than a second one that tracked which
+ // rows were new.
+ //
+ // RECORDED, not fixed here: the caller's `visibility` scope and its
+ // `agentScope` have the same gap at this seam, and they predate this
+ // boundary - a pulled-in successor bypasses `applyVisibilityScope` and
+ // `applyAgentScope` exactly as it bypassed the reach rule. Closing
+ // those means re-resolving the caller's whole filter set after a
+ // post-rank phase, which is a change to the ownership boundary rather
+ // than to this one.
+ const reachable = applyReachFilter(
+ polarized,
+ resolvedTransportReach(opts.transportReach),
+ config.vault,
+ frontmatterCache,
+ );
// Self-tuning reinforce (Search & Recall Quality Suite): opt-in. When
// the caller passes a reinforce set, the persisted ledger lifts
// proven-useful memories by a bounded boost BEFORE the top_k cut, so
@@ -74,8 +102,8 @@ export async function applyPostRankPhases(input: PostRankInput): Promise<PostRan
// untouched; an empty ledger is a no-op either way.
const reinforced =
opts.reinforce !== undefined
- ? applyReinforceBoost(polarized, loadReinforceStrengths(config.vault))
- : polarized;
+ ? applyReinforceBoost(reachable, loadReinforceStrengths(config.vault))
+ : reachable;
// Cross-encoder rerank (retrieval-precision-quality-loop, card A): the
// final reader step, appended AFTER every heuristic rerank. Disabled
// (default) returns the pool unchanged (byte-identical); enabled but
diff --git a/src/core/search/query-cache.ts b/src/core/search/query-cache.ts
index a988ba81..882926f4 100644
--- a/src/core/search/query-cache.ts
+++ b/src/core/search/query-cache.ts
@@ -16,6 +16,7 @@
*/
import { normalizeScopeFilter } from "../scope-key.ts";
+import { resolvedTransportReach } from "../graph/transport-reach.ts";
import type { Store } from "./store.ts";
import type { SearchOptions, SearchOutcome } from "./types.ts";
@@ -100,6 +101,16 @@ export function buildCacheKey(
properties: canonicalProperties(opts.properties),
visibility: opts.visibility ? [...opts.visibility].toSorted() : null,
agentScope: opts.agentScope ?? null,
+ // The transport reach partitions the cache, and unconditionally.
+ // It decides which pages are in the pool at all - a `local` outcome
+ // holds rows the reserved-token rule withholds from `remote` - so a
+ // key that omitted it would let one row serve both, in whichever
+ // direction the operator's own CLI happened to warm it first. Folded
+ // in RESOLVED rather than raw, so an absent reach and an explicit
+ // `remote` key identically; and folded in unconditionally, because
+ // every row written before this boundary existed was computed
+ // without it and must not be served under it.
+ transportReach: resolvedTransportReach(opts.transportReach),
scope: canonicalScope(opts),
// Relational arm (t_09b7ccea) changes the result set, so a per-query
// override partitions the cache. Dropped when absent, so a query that
diff --git a/src/core/search/rerank-eval-gate.ts b/src/core/search/rerank-eval-gate.ts
index e67dabf5..125051a6 100644
--- a/src/core/search/rerank-eval-gate.ts
+++ b/src/core/search/rerank-eval-gate.ts
@@ -17,6 +17,7 @@
import { runRecallBenchmark } from "./benchmark.ts";
import type { RecallBenchmarkDataset, RecallBenchmarkReport } from "./benchmark.ts";
+import { MAINTENANCE_LANE_REACH } from "../graph/transport-reach.ts";
import type { ResolvedRerankConfig, ResolvedSearchConfig } from "./types.ts";
export interface RerankEvalGateOptions {
@@ -66,8 +67,19 @@ export async function runRerankEvalGate(
const minHitDelta = opts.minHitDelta ?? 0.01;
const k = opts.k;
- const baseline = await runRecallBenchmark(withRerank(config, false, kind), dataset, { k });
- const reranked = await runRecallBenchmark(withRerank(config, true, kind), dataset, { k });
+ // An internal gate with no caller: it scores the reranker against the
+ // whole corpus, and a run that stopped seeing reserved pages would
+ // compare the two arms over different vaults. Named through the shared
+ // constant so the claim is the same claim every lane makes.
+ const reach = MAINTENANCE_LANE_REACH;
+ const baseline = await runRecallBenchmark(withRerank(config, false, kind), dataset, {
+ k,
+ transportReach: reach,
+ });
+ const reranked = await runRecallBenchmark(withRerank(config, true, kind), dataset, {
+ k,
+ transportReach: reach,
+ });
const hitDelta = reranked.hitAtK - baseline.hitAtK;
const mrrDelta = reranked.mrr - baseline.mrr;
diff --git a/src/core/search/rerank-fit-check.ts b/src/core/search/rerank-fit-check.ts
index 47345958..8fd6e27c 100644
--- a/src/core/search/rerank-fit-check.ts
+++ b/src/core/search/rerank-fit-check.ts
@@ -27,6 +27,7 @@
*/
import { search } from "./search.ts";
+import { TRANSPORT_REACH } from "../graph/transport-reach.ts";
import { readQueryDemand } from "../brain/query-demand.ts";
import type { ResolvedSearchConfig } from "./types.ts";
import { resolveOpenAiCompatEndpoint } from "./embeddings/provider-resolve.ts";
@@ -171,6 +172,9 @@ async function defaultFetchCandidates(
query,
limit: topK,
selfHeal: false,
+ // Internal measurement lane: the fit check compares rerankers over
+ // this vault's own corpus and hands no page to anyone.
+ transportReach: TRANSPORT_REACH.local,
});
return {
query,
diff --git a/src/core/search/result-filters.ts b/src/core/search/result-filters.ts
index d19c9370..9bca3b31 100644
--- a/src/core/search/result-filters.ts
+++ b/src/core/search/result-filters.ts
@@ -12,7 +12,13 @@ import { parseFrontmatterWithNotices } from "../vault.ts";
import { BRAIN_STATE_REL } from "../brain/paths.ts";
import { DEGRADATION_CODE } from "../integrity/degradation.ts";
import type { FrontmatterMap } from "../types.ts";
-import { isVisible, pageVisibility } from "../graph/visibility.ts";
+import {
+ REMOTE_DENY_VISIBILITY_TOKEN,
+ isRemotelyReadable,
+ isVisible,
+ pageVisibility,
+} from "../graph/visibility.ts";
+import { type TransportReach } from "../graph/transport-reach.ts";
import { isOwnerVisible, pageOwner } from "../graph/agent-scope.ts";
import { scopeAxisReachable, scopeFromFrontmatter, type CompositeScope } from "../scope-key.ts";
import { applyDegreeFilters, filterByProperties, type DegreePredicate } from "./property-filter.ts";
@@ -246,22 +252,100 @@ export function applyDegreeFilter(
return applyDegreeFilters(ranked, predicates, (path) => degreeForPath(snapshot, path));
}
+/**
+ * The reserved-token rule over a ranked result set: root A.
+ *
+ * Separate from {@link applyVisibilityScope}, and the separation is
+ * load-bearing rather than tidy. The two answer different questions -
+ * this one "may a caller at this REACH see the page at all", that one
+ * "does the caller's requested scope reach the page's tags" - and only
+ * the second is a filter the CALLER asked for. The retrieval trail
+ * reports how many rows the caller's own scopes removed, so a reach drop
+ * counted on that side would hand the caller the number of pages it was
+ * withheld from, which is the existence oracle this boundary exists to
+ * close. Running first, and being counted out before the trail's
+ * baseline is taken, is what makes a withheld page indistinguishable
+ * from an absent one.
+ *
+ * The per-path verdict is {@link isPathReadableAtReach}, so this pass
+ * and the by-chunk-id drill-down cannot drift on what "reserved" means -
+ * including the unreadable-file verdict, which an empty frontmatter map
+ * cannot express.
+ */
+export function applyReachFilter(
+ ranked: ReadonlyArray<BrainSearchResult>,
+ reach: TransportReach,
+ vault: string,
+ frontmatterCache: FrontmatterCache,
+): ReadonlyArray<BrainSearchResult> {
+ return ranked.filter((r) => isPathReadableAtReach(vault, r.path, reach, frontmatterCache));
+}
+
+/**
+ * The caller's requested visibility scope over a ranked result set.
+ *
+ * Answers {@link isVisible} only, and is still caller-liftable for every
+ * non-reserved token. It cannot lift the reserved one because
+ * {@link applyReachFilter} has already run and this pass only ever
+ * narrows further.
+ *
+ * Deliberately does NOT see the unmeasurable-page substitution
+ * {@link isPathReadableAtReach} makes: letting that token reach
+ * {@link isVisible} would drop every unreadable page from every
+ * default-scope search at every reach, which is a caller-scope rule this
+ * boundary has no business changing.
+ */
export function applyVisibilityScope(
ranked: ReadonlyArray<BrainSearchResult>,
scope: ReadonlySet<string>,
vault: string,
frontmatterCache: FrontmatterCache,
): ReadonlyArray<BrainSearchResult> {
- const tagsFor = (path: string): string[] => {
- try {
- return pageVisibility(readCachedFrontmatter(frontmatterCache, vault, path));
- } catch {
- return [];
- }
- };
- return ranked.filter((r) => isVisible(tagsFor(r.path), scope));
+ return ranked.filter((r) =>
+ isVisible(pageVisibility(readCachedFrontmatter(frontmatterCache, vault, r.path)), scope),
+ );
+}
+
+/**
+ * May a caller at `reach` read the page at this vault-relative path? The
+ * one place the reserved-token rule meets the filesystem, so every
+ * surface that owns a path - ranked results, the by-chunk-id drill-down,
+ * a report row naming an artifact - resolves it identically.
+ *
+ * FAILS CLOSED at {@link TRANSPORT_REACH.remote} on a page whose file
+ * cannot be READ, the routine trigger being a document still in the index
+ * whose file was deleted, renamed or made unreadable since the last run.
+ * An unreadable visibility claim is not the absence of one, the
+ * convention {@link isPathOwnerVisible} beside it already holds for
+ * ownership. The verdict comes from {@link readCachedFrontmatterEntry}
+ * rather than from an empty metadata map, because the parser resolves an
+ * unreadable file to `{}` and never throws, so a `catch` arm here would
+ * be dead code. At {@link TRANSPORT_REACH.local} the page is readable
+ * unconditionally - that caller can open the file directly anyway, and
+ * hiding a stale index row from the operator who has to fix it helps
+ * nobody.
+ */
+export function isPathReadableAtReach(
+ vault: string,
+ path: string,
+ reach: TransportReach,
+ frontmatterCache: FrontmatterCache,
+): boolean {
+ const entry = readCachedFrontmatterEntry(frontmatterCache, vault, path);
+ const tags = entry.unreadable ? UNMEASURABLE_VISIBILITY : pageVisibility(entry.meta);
+ return isRemotelyReadable(tags, reach);
}
+/**
+ * The tag list an unreadable page answers with: the reserved token, so a
+ * page nobody can measure is treated exactly as one that reserved itself.
+ * Spelled as a constant rather than an inline literal so the fail-closed
+ * choice is visible at the definition rather than inferred from a branch.
+ */
+const UNMEASURABLE_VISIBILITY: ReadonlyArray<string> = Object.freeze([
+ REMOTE_DENY_VISIBILITY_TOKEN,
+]);
+
/**
* Composite scope filter (t_37c05a34): drop results outside the requested
* session/project scope. Per axis, a null request does not filter and an
diff --git a/src/core/search/schema.ts b/src/core/search/schema.ts
index 0b745f80..7841d01b 100644
--- a/src/core/search/schema.ts
+++ b/src/core/search/schema.ts
@@ -10,13 +10,15 @@
import { Database } from "bun:sqlite";
import { SearchError } from "./types.ts";
+import { pageVisibility } from "../graph/visibility.ts";
+import { parseFrontmatterText } from "../vault.ts";
/**
* Latest schema version this code understands. A DB with a value above
* this raises `SCHEMA_MISMATCH` on open β€” the operator must reindex
* with a newer binary.
*/
-export const LATEST_SCHEMA_VERSION = 11;
+export const LATEST_SCHEMA_VERSION = 12;
/**
* The one command that rebuilds an index this binary cannot read. Every
@@ -546,8 +548,106 @@ export const MIGRATIONS: ReadonlyArray<Migration> = Object.freeze([
}
},
},
+ {
+ // v12 (private-is-not-a-suggestion) - what the INDEX could measure of
+ // each page's `visibility:` frontmatter, materialised so a diagnostic
+ // does not have to scan every chunk body to answer it.
+ //
+ // Three states, all three distinct:
+ //
+ // - a JSON array of the page's normalised tokens - measured;
+ // - `[]` - measured, and the page declares none;
+ // - NULL - this document has no chunk zero at all, so the index
+ // holds nothing to measure. Not a synonym for `[]`.
+ //
+ // The BACKFILL is the whole of why this migration is more than an
+ // `ALTER TABLE`. A column added without one is NULL for every
+ // existing row, and treating NULL as reserved - which is the only
+ // fail-closed reading of "unmeasured" - would withhold every document
+ // in every vault on upgrade, including the overwhelming majority that
+ // never used the field. The frontmatter is already IN the index:
+ // `chunker.ts`'s `packBlocks` emits a page's frontmatter block as its
+ // own chunk, verbatim, at `chunk_index = 0`. So the backfill is one
+ // table scan and a parse per document, with no vault walk and no
+ // operator action.
+ //
+ // It runs INSIDE this migration's transaction, and the reason is
+ // atomicity rather than speed: a half-filled column leaves measurable
+ // rows reading as unmeasured, which is the blackout this backfill
+ // exists to prevent, and a crash mid-pass would leave exactly that.
+ //
+ // RECORDED LIMIT: an UNTERMINATED frontmatter block is measured as
+ // `[]` rather than as NULL. The design expected NULL, and the index
+ // cannot produce it: `chunker.ts`'s `readFrontmatter` drops the
+ // opening `---` and keeps the rest as body, so chunk zero of a page
+ // with an unterminated block is byte-indistinguishable from chunk
+ // zero of a page with no frontmatter at all. It does not matter,
+ // because `parseFrontmatterText` reads an unterminated block on the
+ // REAL FILE as declaring nothing too - so the column and the live
+ // boundary at the three read roots agree, rather than one of them
+ // being wrong in private.
+ version: 12,
+ up(db) {
+ const docCols = db.query<{ name: string }, []>("PRAGMA table_info(documents)").all();
+ if (!docCols.some((c) => c.name === DOCUMENT_VISIBILITY_COLUMN)) {
+ db.exec(`ALTER TABLE documents ADD COLUMN ${DOCUMENT_VISIBILITY_COLUMN} TEXT`);
+ }
+ backfillDocumentVisibility(db);
+ },
+ },
]);
+/**
+ * The `documents` column holding what the index measured of a page's
+ * `visibility:` frontmatter. Named once: the migration, the store, the
+ * indexer and the diagnostics all spell it from here.
+ */
+export const DOCUMENT_VISIBILITY_COLUMN = "visibility";
+
+/** The measured-and-empty value, so `[]` is never written as a literal. */
+export const DOCUMENT_VISIBILITY_NONE = "[]";
+
+/** The `chunk_index` a page's frontmatter block lands at, when it has one. */
+const FRONTMATTER_CHUNK_INDEX = 0;
+
+/**
+ * Encode a page's normalised visibility tokens for the column.
+ *
+ * JSON rather than a delimited list, because a visibility token is an
+ * opaque string from a page's frontmatter and any delimiter this module
+ * chose could appear inside one - which would turn one token into two and
+ * silently change what the page declared.
+ */
+export function encodeDocumentVisibility(tokens: ReadonlyArray<string>): string {
+ return JSON.stringify(tokens);
+}
+
+/**
+ * Fill {@link DOCUMENT_VISIBILITY_COLUMN} for every row that has no value
+ * yet, from the frontmatter chunk the index already holds.
+ *
+ * A document with no chunk zero is left NULL - the index holds nothing to
+ * measure, and saying "no tokens" about it would be a claim nobody made.
+ */
+function backfillDocumentVisibility(db: Database): void {
+ const rows = db
+ .query<{ id: number; content: string | null }, [number]>(
+ `SELECT d.id AS id, c.content AS content FROM documents d ` +
+ `LEFT JOIN chunks c ON c.document_id = d.id AND c.chunk_index = ?1 ` +
+ `WHERE d.${DOCUMENT_VISIBILITY_COLUMN} IS NULL`,
+ )
+ .all(FRONTMATTER_CHUNK_INDEX);
+ if (rows.length === 0) return;
+ const update = db.query<never, [string, number]>(
+ `UPDATE documents SET ${DOCUMENT_VISIBILITY_COLUMN} = ?1 WHERE id = ?2`,
+ );
+ for (const row of rows) {
+ if (row.content === null) continue;
+ const [meta] = parseFrontmatterText(row.content);
+ update.run(encodeDocumentVisibility(pageVisibility(meta)), row.id);
+ }
+}
+
// ─────────────────────────────────────────────────────────────────────────────
// The expected-object manifest
// ─────────────────────────────────────────────────────────────────────────────
diff --git a/src/core/search/serialize.ts b/src/core/search/serialize.ts
index 6b9c15d0..58a71a91 100644
--- a/src/core/search/serialize.ts
+++ b/src/core/search/serialize.ts
@@ -110,6 +110,8 @@ export function serializeVisibilityHonestyFinding(
return {
excluded_surface_count: finding.excludedSurfaceCount,
total_surface_count: finding.totalSurfaceCount,
+ reserved_document_count: finding.reservedDocumentCount,
+ unmeasured_document_count: finding.unmeasuredDocumentCount,
};
}
diff --git a/src/core/search/store.ts b/src/core/search/store.ts
index 890eed08..2761c75a 100644
--- a/src/core/search/store.ts
+++ b/src/core/search/store.ts
@@ -88,7 +88,7 @@ export {
export { peekPendingVectorsSync } from "./store/counts.ts";
-export { peekVisibilityTagPresence } from "./store/visibility-tag.ts";
+export { peekVisibilityColumnCensus, type VisibilityColumnCensus } from "./store/visibility-tag.ts";
export {
auditEmbedderRecord,
diff --git a/src/core/search/store/documents.ts b/src/core/search/store/documents.ts
index a946b3ad..4d656857 100644
--- a/src/core/search/store/documents.ts
+++ b/src/core/search/store/documents.ts
@@ -7,7 +7,11 @@
import { Database } from "bun:sqlite";
import { isEventAnchorSource, type EventAnchor } from "../event-anchor.ts";
-import { documentBasename } from "../schema.ts";
+import {
+ DOCUMENT_VISIBILITY_COLUMN,
+ documentBasename,
+ encodeDocumentVisibility,
+} from "../schema.ts";
import { SearchError } from "../types.ts";
import { nowIso } from "./sql.ts";
import { purgeVecRowsForDocument } from "./vectors.ts";
@@ -58,6 +62,21 @@ export interface DocumentInput {
* because a hard time filter now depends on the difference.
*/
readonly eventAnchor?: EventAnchor | null;
+ /**
+ * The page's normalised `visibility:` tokens, as {@link pageVisibility}
+ * reads them - an empty array for a page that declares none (v12).
+ *
+ * ABSENT means the caller did not measure them, and the column is left
+ * NULL. That is a third state and not a synonym for the empty array:
+ * "this page declares no visibility" and "nobody looked" are different
+ * statements, and only the first is something the page said.
+ *
+ * The column records what the INDEX knows. It is not the read boundary
+ * - that is the live frontmatter check at the three read roots
+ * (`isPathReadableAtReach`), which reads the file rather than a
+ * snapshot of it and is therefore never stale by a whole index run.
+ */
+ readonly visibility?: ReadonlyArray<string>;
}
export interface DocumentSummary {
@@ -118,6 +137,7 @@ export function upsertDocument(db: Database, doc: DocumentInput): number {
number | null,
string | null,
number,
+ string | null,
string,
string,
string,
@@ -125,8 +145,9 @@ export function upsertDocument(db: Database, doc: DocumentInput): number {
>(
"INSERT INTO documents(path, basename, title, content_hash, mtime, size, page_type, authored_at, " +
" event_anchor_start_ms, event_anchor_end_ms, event_anchor_source, event_anchor_examined, " +
+ ` ${DOCUMENT_VISIBILITY_COLUMN}, ` +
" created_at, updated_at, indexed_at) " +
- "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) " +
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) " +
"ON CONFLICT(path) DO UPDATE SET " +
" basename = excluded.basename, " +
" title = excluded.title, " +
@@ -139,6 +160,7 @@ export function upsertDocument(db: Database, doc: DocumentInput): number {
" event_anchor_end_ms = excluded.event_anchor_end_ms, " +
" event_anchor_source = excluded.event_anchor_source, " +
" event_anchor_examined = excluded.event_anchor_examined, " +
+ ` ${DOCUMENT_VISIBILITY_COLUMN} = excluded.${DOCUMENT_VISIBILITY_COLUMN}, ` +
" updated_at = excluded.updated_at, " +
" indexed_at = excluded.indexed_at " +
"RETURNING id",
@@ -158,6 +180,8 @@ export function upsertDocument(db: Database, doc: DocumentInput): number {
// Examined iff the caller stated an answer. `null` IS an answer
// ("this note declares nothing"); leaving the field out is not.
doc.eventAnchor === undefined ? EXAMINED_NO : EXAMINED_YES,
+ // Absent means unmeasured, which is NULL - see `DocumentInput`.
+ doc.visibility === undefined ? null : encodeDocumentVisibility(doc.visibility),
now,
now,
now,
diff --git a/src/core/search/store/visibility-tag.ts b/src/core/search/store/visibility-tag.ts
index fc5c2b35..e2ebced2 100644
--- a/src/core/search/store/visibility-tag.ts
+++ b/src/core/search/store/visibility-tag.ts
@@ -1,78 +1,119 @@
/**
- * Whether the index holds ANY evidence that a page declares
- * `visibility:` frontmatter, read without a vault walk
- * (nothing-writes-silently, unit H).
+ * What the index knows about `visibility:` frontmatter, read off the
+ * column the indexer materialises rather than by scanning chunk bodies
+ * (private-is-not-a-suggestion, unit 6).
*
- * The chunker (`chunker.ts`'s `packBlocks`) emits a page's frontmatter
- * block as its own chunk, verbatim, ahead of every other chunk the page
- * produces - so `chunks.content` at `chunk_index = 0` IS the page's raw
- * YAML text when the page has frontmatter at all, and the FIRST real
- * content chunk (never frontmatter) when it does not. That is a
- * structural fact about how the index is built, not a coincidence this
- * module is trusting: it is exercised as `INTRUDER_CHUNK_INDEX_ZERO` in
- * `tests/core/search/visibility-tag-presence.test.ts`.
+ * ## What this replaced, and why
*
- * That makes "does any page use `visibility:`" answerable from the
- * ALREADY-BUILT index - no filesystem walk, no per-page frontmatter
- * parse, and no new table. It is imprecise in the direction that costs
- * nothing: a
- * frontmatter VALUE that happens to contain the literal substring
- * `visibility:` (a title field quoting the word, say) reads as a tagged
- * vault when none exists. `search check`'s honesty finding this feeds
- * is worded to survive that - it names a caller-supplied filter, not an
- * exact count of tagged pages - and the alternative, parsing every
- * frontmatter block back out of `chunks` to confirm the key rather than
- * the substring, re-derives the vault-walk cost this module exists to
- * avoid.
+ * Until v12 the answer came from a `LIKE '%visibility:%'` scan of every
+ * document's `chunk_index = 0` row - a full table scan whose cheapest
+ * case was a vault that DOES use the field and whose worst case was the
+ * common one, and which was imprecise in a direction it could not
+ * correct: a frontmatter VALUE quoting the literal `visibility:` (a title
+ * quoting the word, say) read as a tagged vault when none existed.
*
- * ## What it costs, stated rather than implied
+ * `documents.visibility` is that same fact, decided by the same
+ * {@link pageVisibility} the read boundary uses, written once per upsert
+ * and backfilled for pre-existing rows by migration 12. The scan and its
+ * substring guess are both gone.
*
- * It is a SCAN of `chunks`, not an index lookup. No index serves it and
- * none could: the only index on the table is `idx_chunks_document`
- * (`schema.ts`), and a leading-wildcard `LIKE` is unindexable in any
- * case, so `chunk_index = ?` is a filter applied per row rather than a
- * seek. `EXISTS` stops at the first match, which makes a vault that DOES
- * use the field cheap and the common case - a vault that never has -
- * the worst one: every chunk body is read to conclude "no".
+ * ## Three states, and why the count of the third is reported
*
- * What makes that affordable is WHERE it runs, not how small it is: once
- * per `indexCheck`, an operator-invoked diagnostic, and nowhere on a
- * query path. A caller wanting this answer per search would need a
- * recorded flag rather than this scan.
+ * NULL means the index holds no chunk zero for that document and
+ * therefore measured nothing. It is not "no tokens", and
+ * {@link countUnmeasuredDocuments} exists so `search check` can report
+ * that population rather than absorb it into the measured one.
+ *
+ * ## What this is NOT
+ *
+ * It is not the read boundary. That is the live frontmatter check at the
+ * three read roots (`isPathReadableAtReach`), which reads the FILE. A
+ * column is a snapshot of the last index run, and a page reserved a
+ * minute ago must be reserved now rather than at the next run - so the
+ * column reports, and the file decides.
*/
import { Database } from "bun:sqlite";
+import { DOCUMENT_VISIBILITY_COLUMN, DOCUMENT_VISIBILITY_NONE } from "../schema.ts";
import { peekReadonlyIndex, type IndexPeek } from "./state.ts";
-/** The `chunk_index` a page's frontmatter block lands at, when it has one. */
-const FRONTMATTER_CHUNK_INDEX = 0;
-
-/** Substring a frontmatter chunk carries when the page declares the key. */
-const VISIBILITY_KEY_PATTERN = "%visibility:%";
-
/**
- * True when at least one document's `chunk_index = 0` row contains the
- * literal substring `visibility:`. One `LIKE` scan of `chunks`, stopping
- * at the first hit - see the module docblock for what that costs and why
- * this is not the indexed lookup its shape suggests.
+ * True when at least one document was measured and declares at least one
+ * visibility token. Exact: `[]` is the measured-and-empty value and NULL
+ * is the unmeasured one, so neither can read as a tagged page.
*/
export function anyVisibilityTagPresent(db: Database): boolean {
const row = db
- .query<{ present: number }, [string, number]>(
- "SELECT EXISTS(SELECT 1 FROM chunks WHERE content LIKE ?1 AND chunk_index = ?2) AS present",
+ .query<{ present: number }, [string]>(
+ `SELECT EXISTS(SELECT 1 FROM documents ` +
+ `WHERE ${DOCUMENT_VISIBILITY_COLUMN} IS NOT NULL ` +
+ `AND ${DOCUMENT_VISIBILITY_COLUMN} <> ?1) AS present`,
)
- .get(VISIBILITY_KEY_PATTERN, FRONTMATTER_CHUNK_INDEX);
+ .get(DOCUMENT_VISIBILITY_NONE);
return row?.present === 1;
}
/**
- * {@link anyVisibilityTagPresent} for an index path, without opening a
+ * How many indexed documents the index measured nothing for.
+ *
+ * Reported rather than absorbed: these rows are the legacy population a
+ * migration could not read, and a diagnostic that folded them into "no
+ * tokens" would be answering a question nobody could check.
+ */
+export function countUnmeasuredDocuments(db: Database): number {
+ const row = db
+ .query<{ n: number }, []>(
+ `SELECT COUNT(*) AS n FROM documents WHERE ${DOCUMENT_VISIBILITY_COLUMN} IS NULL`,
+ )
+ .get();
+ return row?.n ?? 0;
+}
+
+/**
+ * How many indexed documents declare the token reserved against remote
+ * reads - the population this boundary withholds from a remote caller.
+ *
+ * `json_each` rather than a substring match, so a token that CONTAINS the
+ * reserved one is not counted as it.
+ */
+export function countRemoteReservedDocuments(db: Database, token: string): number {
+ const row = db
+ .query<{ n: number }, [string]>(
+ `SELECT COUNT(*) AS n FROM documents ` +
+ `WHERE ${DOCUMENT_VISIBILITY_COLUMN} IS NOT NULL ` +
+ `AND EXISTS(SELECT 1 FROM json_each(documents.${DOCUMENT_VISIBILITY_COLUMN}) ` +
+ `WHERE json_each.value = ?1)`,
+ )
+ .get(token);
+ return row?.n ?? 0;
+}
+
+/**
+ * The two populations `search check` reports beside the presence flag,
+ * read in one open so the diagnostic pays one probe rather than three.
+ *
+ * The one seam into this module from an index PATH, without opening a
* `Store` - the same seam {@link peekPendingVectorsSync} and
* {@link readEmbedderRecordCensusSync} use, and for the same reason:
* `indexCheck` probes an in-memory database and never touches the real
- * index otherwise.
+ * index otherwise. A presence-only sibling stood beside it until this
+ * census subsumed its one production caller; it was kept alive by its own
+ * test, which is a passing suite over a path the product no longer walks.
*/
-export function peekVisibilityTagPresence(dbPath: string): IndexPeek<boolean> {
- return peekReadonlyIndex(dbPath, (_read, db) => anyVisibilityTagPresent(db));
+export interface VisibilityColumnCensus {
+ readonly tagged: boolean;
+ readonly unmeasured: number;
+ readonly reserved: number;
+}
+
+export function peekVisibilityColumnCensus(
+ dbPath: string,
+ reservedToken: string,
+): IndexPeek<VisibilityColumnCensus> {
+ return peekReadonlyIndex(dbPath, (_read, db) => ({
+ tagged: anyVisibilityTagPresent(db),
+ unmeasured: countUnmeasuredDocuments(db),
+ reserved: countRemoteReservedDocuments(db, reservedToken),
+ }));
}
diff --git a/src/core/search/tuning.ts b/src/core/search/tuning.ts
index 7e6abee2..eb23de4a 100644
--- a/src/core/search/tuning.ts
+++ b/src/core/search/tuning.ts
@@ -40,6 +40,7 @@ import {
TUNING_TRAVERSAL_DEPTHS,
tuningPath,
} from "./tuning-store.ts";
+import type { TransportReach } from "../graph/transport-reach.ts";
import type { ResolvedSearchConfig, TunedParameters } from "./types.ts";
export interface TuningEvaluation {
@@ -61,6 +62,14 @@ export interface TuneRecallOptions {
readonly k?: number;
/** Injected clock for the persisted `evaluated_at` stamp. */
readonly now: Date;
+ /**
+ * The reach the party that supplied this dataset was established at,
+ * forwarded verbatim to every grid cell's benchmark run. Absent
+ * resolves to the narrowest there - see
+ * {@link RecallBenchmarkOptions.transportReach}, which is where the
+ * reason lives.
+ */
+ readonly transportReach?: TransportReach;
}
/** The full bounded grid in stable order (defaults first). */
@@ -96,6 +105,7 @@ export async function tuneRecall(
grid.map(async (params): Promise<TuningEvaluation> => {
const report = await runRecallBenchmark(applyTunedParameters(config, params), dataset, {
...(opts.k !== undefined ? { k: opts.k } : {}),
+ ...(opts.transportReach !== undefined ? { transportReach: opts.transportReach } : {}),
expand: params.expansion,
});
return Object.freeze({ params, mrr: report.mrr, hitAtK: report.hitAtK });
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index abfb6fc9..04a35beb 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -13,6 +13,7 @@
* before is still exported from this path.
*/
+import type { TransportReach } from "../graph/transport-reach.ts";
import type { DegradationNotice } from "../integrity/degradation.ts";
import type { StampMismatch } from "../integrity/stamp.ts";
import type { ReconciliationOutcome, ReconciliationReport } from "../reconciliation-report.ts";
@@ -499,6 +500,24 @@ export interface VisibilityHonestyFinding {
readonly excludedSurfaceCount: number;
/** Every callable surface the registry classifies, covered or excluded. */
readonly totalSurfaceCount: number;
+ /**
+ * Indexed documents declaring the token reserved against remote reads -
+ * the population this boundary withholds from a remote caller.
+ *
+ * Reported because the boundary is a BEHAVIOUR CHANGE for a vault that
+ * tags pages, and an operator has to be able to see its size rather
+ * than infer it from a search that came back shorter.
+ */
+ readonly reservedDocumentCount: number;
+ /**
+ * Indexed documents the index measured nothing for - it holds no
+ * frontmatter chunk to read.
+ *
+ * Reported rather than absorbed into "declares nothing": the two are
+ * different statements, and folding the legacy population into the
+ * measured one would answer a question nobody could check.
+ */
+ readonly unmeasuredDocumentCount: number;
}
export interface IndexCheckReport {
@@ -629,6 +648,19 @@ export interface ExpandHitInput {
* would confirm the chunk exists. Omitted / blank filters nothing.
*/
readonly agentScope?: string;
+ /**
+ * How far this caller reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`). Absent resolves to the
+ * narrowest, on the same terms {@link SearchOptions.transportReach}
+ * does.
+ *
+ * A chunk id is a sequential integer, so this surface is the enumerable
+ * back door to every reserved page in the index. A page reserved
+ * against remote reads is refused here with the SAME error an absent
+ * chunk produces - the convention the owner-scope refusal above already
+ * follows, for the same reason.
+ */
+ readonly transportReach?: TransportReach;
}
/**
@@ -813,8 +845,30 @@ export interface SearchOptions {
* a page that declares visibility values is returned only when this
* scope includes one of them. Absent/empty = default scope (reaches
* untagged pages only). See src/core/graph/visibility.ts.
+ *
+ * This argument NARROWS and cannot lift: a scope naming
+ * {@link REMOTE_DENY_VISIBILITY_TOKEN} does not make a page reserved
+ * against remote reads readable at {@link TRANSPORT_REACH.remote}. See
+ * {@link SearchOptions.transportReach}.
*/
readonly visibility?: ReadonlyArray<string>;
+ /**
+ * How far the caller of this search had to reach to get here, minted by
+ * the transport that accepted the request
+ * (`src/core/graph/transport-reach.ts`).
+ *
+ * Absent resolves to {@link TRANSPORT_REACH.remote}, the narrowest: a
+ * search whose caller nobody established anything about is not a search
+ * that proved local access. Every internal lane that must see the whole
+ * corpus - benchmarks, recall feedback, rerank fit - passes
+ * {@link TRANSPORT_REACH.local} explicitly, and so does the CLI, which
+ * runs in the operator's own shell.
+ *
+ * NOT to be confused with {@link SearchOptions.disclosure}, which is
+ * the result-DEPTH mode; this one decides which pages exist for this
+ * caller at all.
+ */
+ readonly transportReach?: TransportReach;
/**
* Requested agent-ownership scope (Unit 5). When set, a page that
* declares an `owner:` frontmatter token is returned only if its owner
diff --git a/src/core/search/visibility-surface-registry.ts b/src/core/search/visibility-surface-registry.ts
index 814527df..9675cd2e 100644
--- a/src/core/search/visibility-surface-registry.ts
+++ b/src/core/search/visibility-surface-registry.ts
@@ -1,36 +1,50 @@
/**
* Every surface that can hand a vault note's path, title, or body back to
- * a caller, classified as visibility-COVERED (routes through
- * `applyVisibilityScope`) or EXCLUDED with a written reason
- * (nothing-writes-silently, unit H, form B).
+ * a caller, classified as visibility-COVERED (a read root decides for it)
+ * or EXCLUDED with a written reason (nothing-writes-silently, unit H,
+ * form B).
*
- * `graph/visibility.ts`'s `visibility:` frontmatter field is real and
- * wired into exactly one place: `pipeline/pool-filters.ts:130`, inside
- * `search()`. It is caller-liftable scoping, not a boundary - any caller
- * may pass `visibility: ["private"]` and read a tagged page - but even
- * that weaker guarantee only holds for the ONE lane that calls `search()`.
- * Everywhere else, a page's tag is decorative. This module is the
- * enumeration that makes the gap a measured fact instead of a claim:
+ * `graph/visibility.ts`'s `visibility:` field carries two independent
+ * rules, and this list is about the second of them:
+ *
+ * - the caller's requested SCOPE, which any caller may lift by asking
+ * for a token, and which reaches only the lanes that call `search()`;
+ * - ONE reserved token, which a caller cannot lift and which three read
+ * roots enforce - the search pipeline, `listVaultPages`, and the
+ * key-addressed reads.
+ *
+ * This module is the enumeration that makes the remaining gap a measured
+ * fact instead of a claim:
* {@link tests/core/architecture/visibility-surface-census.test.ts} pins
- * that a mechanical sweep of `src/mcp/` and `src/cli/` finds nothing this
- * list does not already carry, and `search check` derives its honesty
- * finding's count from {@link excludedCallableVisibilitySurfaces} rather
- * than a hand-written number.
+ * that a mechanical sweep of `src/mcp/`, `src/cli/` and `src/openclaw/`
+ * finds nothing this list does not already carry, and `search check`
+ * derives its honesty finding's counts from
+ * {@link excludedCallableVisibilitySurfaces} and from the index's own
+ * column rather than from hand-written numbers.
*
* The list is the census's POPULATION, not a claim to be every surface
* there is: the MCP half is swept mechanically with the blind spots that
* test's docblock states, and the CLI half is hand-enumerated one row per
* MCP mirror. The `search check` line that reports it says so.
*
- * This module makes NO enforcement change. It does not touch
- * `graph/visibility.ts`, the indexer, `listVaultPages`, or the
- * owner-scope path - see the census test's docblock for the coverage map
- * a future enforcement wave (Unit H form A, parked) would need.
+ * HISTORY, because a stale claim here is worse than none. This module
+ * shipped as a pure measurement, and its header said so: "makes NO
+ * enforcement change ... a future enforcement wave (Unit H form A,
+ * parked)". That wave is this branch. `graph/visibility.ts`, the indexer
+ * and `listVaultPages` are all touched now, the reserved token is
+ * enforced at the three roots, and the reasons below say per row which
+ * root covers a surface - so the header that described the parked state
+ * would now be describing a state that no longer exists.
*/
-/** Whether a surface's data path passes through `applyVisibilityScope`. */
+/** Whether a read root decides what a surface may hand back. */
export const VISIBILITY_SURFACE_CATEGORY = Object.freeze({
- /** Routes through `applyVisibilityScope`, directly or via `search()`. */
+ /**
+ * A read root decides for it: the search pipeline's pool filters, the
+ * `listVaultPages` walk, or the key-addressed read's own ask at the
+ * site of the read. Was "routes through `applyVisibilityScope`", which
+ * described the only root that existed when this list was written.
+ */
covered: "covered",
/** Can return note path/title/body without ever consulting `visibility:`. */
excluded: "excluded",
@@ -104,22 +118,23 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain_search_expand",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "expandHit() (core/search/cards.ts) hydrates a chunk_id directly off the store and checks " +
- "only isPathOwnerVisible, and only when the caller supplies agentScope - it never calls " +
- "applyVisibilityScope or isVisible. A caller holding any valid chunk_id for a " +
- "visibility-tagged page - not necessarily one it received from a filtered brain_search call " +
- "- can read the full note through this tool.",
+ "expandHit() (core/search/cards.ts) hydrates a chunk_id straight off the store, so it is " +
+ "root C - the key-addressed read. It asks isPathReadableAtReach on EVERY call rather than " +
+ "only when an argument arrived, and refuses a reserved page with the SAME error an absent " +
+ "chunk produces, because a chunk id is a sequential integer and a distinguishable refusal " +
+ "over an enumerable key space is an existence oracle.",
},
{
surface: "second_brain_query",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "toolQuery (src/mcp/tools.ts) lists pages with listVaultPages(), which accepts only " +
- "skipDirs/skipFiles, and applies its own owner-scope check over the parsed frontmatter - " +
- "visibility: is never read on this path.",
+ "toolQuery (src/mcp/tools.ts) lists pages with listVaultPages(), which is root B: the walk " +
+ "takes the reach the transport minted and drops a reserved page over the frontmatter it has " +
+ "already parsed, before the sort and before the array leaves the function - so the ownership " +
+ "filter below it and the total it reports both see the same pages the caller does.",
},
{
surface: "brain_context_pack",
@@ -134,20 +149,25 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain_query",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "queryByPreference / queryByTopic (core/brain/query.ts) return Brain preference, retired " +
- "and log records - id, principle, evidence trail - straight off disk with no visibility " +
- "check anywhere in the read path.",
+ "queryByPreference / queryByTopic (core/brain/query.ts) return Brain records by id, so this " +
+ "is root C over reference-shaped rows. The topic mode carries the reach into the SELECTION, " +
+ "because a topic resolves to exactly one preference and filtering afterwards would report a " +
+ "topic as having no rule whenever a reserved one sorted first; the signals, the log events " +
+ "and the preference-mode lookup are filtered through reachView, and a reserved preference " +
+ "answers with the message an absent one produces.",
},
{
surface: "brain_backlinks",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "buildBacklinkIndex (core/brain/backlinks.ts) walks the vault with readdirSync + " +
- "parseFrontmatter directly, gated only by ownerScopeView; visibility: is not among the " +
- "fields it consults.",
+ "buildBacklinkIndex (core/brain/backlinks.ts) walks the vault itself, and every ref it " +
+ "yields NAMES its source artifact - so root C is applied to the refs as well as to the " +
+ "target. A withheld target answers as an absent one (the empty backlink document) rather " +
+ "than refusing, because an unknown target is a legitimate zero here and a refusal would be " +
+ "the one response shape that proves the page exists.",
},
{
surface: "brain_unlinked_mentions",
@@ -180,22 +200,29 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain_bridges",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "discoverBridges (core/brain/link-graph/bridge-discovery.ts) proposes links between " +
- "embedding-near notes read via listVaultPages and a raw Store handle, and list reads " +
- "Brain/proposals/bridges.md back - source/target note paths in both cases, with no " +
- "visibility check on either side of a proposed pair.",
+ "BOTH modes, because classifying the tool off the list mode alone was the registry making " +
+ "a claim the tool did not hold. The list mode readFileSyncs Brain/proposals/bridges.md by " +
+ "path rather than through a read root, so it asks reachView at the site of the read and a " +
+ "reserved proposals page answers exactly as an absent one does - registered as a guarded " +
+ "direct vault read by the root-closure sweep in the architecture census. The discover mode " +
+ "returned discoverBridges()'s proposals verbatim, each naming two pages by path off the " +
+ "vec index, which keeps reserved pages by design (the column reports, it does not " +
+ "exclude); it now drops a proposal WHOLE when either end is withheld. Detection stays " +
+ "vault-wide and the shared artifact is still written unfiltered - a bridge proposed from " +
+ "the visible half of a link graph would differ per caller - so the rule is applied to what " +
+ "the caller is told, which is the same shape brain_clusters run uses.",
},
{
surface: "brain_clusters",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "detectCommunities / materializeClusterNotes (core/brain/link-graph/communities.ts) read " +
- "the link graph off a raw Store handle and member titles via parseFrontmatter, then " +
- "materialize cluster notes naming every member page - no visibility check anywhere in the " +
- "pass.",
+ "the list mode readdirSyncs Brain/clusters/*.md by path rather than through a read root, so " +
+ "it asks reachView at the site of the read: a withheld cluster is dropped and nothing " +
+ "counts it, which is the row the root-closure sweep in " +
+ "tests/core/architecture/visibility-surface-census.test.ts registers as guarded.",
},
{
surface: "brain_moc_audit",
@@ -209,13 +236,11 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain_deep_synthesis",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "deepSynthesis (core/brain/deep-synthesis.ts) is mixed rather than uniformly unfiltered: " +
- "its matched-notes component calls search() and inherits pool-filters, but its " +
- "knowledge-gap component (dangling wikilinks) walks the vault directly via walkVault " +
- "(core/search/walker.ts), which applies no visibility check. The dossier as a whole cannot " +
- "be called covered because one of its two note-reading paths is not.",
+ "deepSynthesis (core/brain/deep-synthesis.ts) reaches its matched notes through search(), " +
+ "so it is covered transitively by root A: the tool threads contextReach(ctx) into " +
+ "SearchOptions.transportReach and inherits the same pool-filters gate brain_search has.",
},
{
surface: "brain_idea_discovery",
@@ -416,18 +441,83 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain_recall_feedback",
kind: K.mcpTool,
- category: C.excluded,
+ category: C.covered,
reason:
- "records a relevance verdict for a prior recall result and returns a confirmation, not note " +
- "content; included for completeness of the file-level sweep only.",
+ "captureRecallFeedback (core/search/feedback.ts) re-runs the judged query through search() " +
+ "and reports whether the path came back, which is an existence oracle for any page the " +
+ "caller cannot read - so the re-run carries contextReach(ctx) and is covered by root A.",
},
{
surface: "brain_eval",
kind: K.mcpTool,
+ category: C.covered,
+ reason:
+ "scores retrieval quality (hit@k, MRR, …) over a CALLER-supplied dataset, so 'metrics, not " +
+ "note bodies' was the wrong reason to exclude it: `hit` / `rank` / `expectedFound` answer " +
+ "for caller-named paths and `answerContained` substring-tests a caller-supplied string " +
+ "against the retrieved content, which is an existence oracle and a content oracle over " +
+ "whatever corpus the run scored. runRecallBenchmark now takes the reach and passes it to " +
+ "every search() it makes, so the benchmark measures the corpus this caller can reach and " +
+ "root A does the withholding. brain_tune inherits it: the grid is scored with the same " +
+ "benchmark.",
+ },
+ {
+ surface: "brain_hygiene",
+ kind: K.mcpTool,
+ category: C.covered,
+ reason:
+ "the freshness detector's population comes from listVaultPages(MAINTENANCE_LANE_REACH), so " +
+ "reserved pages are walked IN on purpose - a scan that stopped seeing them would diagnose a " +
+ "smaller vault than the one it is diagnosing - and every finding puts its page's " +
+ "vault-relative path in `targets` with a title stating a fact about it. The rule is asked " +
+ "on the seam the owner rule already sits on, over what the caller is told, so a detector " +
+ "registered after this one inherits it; `counts` is recomputed from the visible findings and " +
+ "a withheld " +
+ "id lands in `unknown_ids` exactly as one nobody issued does.",
+ },
+ {
+ surface: "brain_skill_proposals",
+ kind: K.mcpTool,
+ category: C.covered,
+ reason:
+ "the page_candidates operation calls planSkillPageDrafts, which walks with " +
+ "MAINTENANCE_LANE_REACH, and returns a path and title per page in `admitted` and in " +
+ "`skipped` - the latter with a `detail` stating why the gate turned the page down. Both " +
+ "lists are filtered at the handler and `pages_scanned` is recomputed from them whenever a " +
+ "rule is live, because a corpus size taken before the filter states how many pages were " +
+ "withheld.",
+ },
+ {
+ surface: "brain_procedural_memory",
+ kind: K.mcpTool,
category: C.excluded,
reason:
- "scores retrieval quality (hit@k, MRR, …) over an operator-supplied dataset and returns " +
- "metrics, not note bodies; included for completeness of the file-level sweep only.",
+ "collectEntries walks the configured roots with parseFrontmatter and returns `sourcePath` " +
+ "and `title` per entry, so this surface DOES disclose a page's path and title - it is " +
+ "excluded rather than swept in for completeness, and the distinction is the point of the " +
+ "row. It reads procedure-kind pages under caller-named roots rather than through any of " +
+ "the three read roots, and closing it means giving that walk a reach the way listVaultPages " +
+ "has one, which is a fourth root to build rather than a filter to add.",
+ },
+ {
+ surface: "brain_procedural_graph",
+ kind: K.mcpTool,
+ category: C.excluded,
+ reason:
+ "rebuilds the procedural graph and hints over the same population brain_procedural_memory " +
+ "walks, and reports node/edge/entry COUNTS plus generated_at rather than any page's path, " +
+ "title or body - so it inherits that surface's population without inheriting its " +
+ "disclosure. Excluded on the same terms and named here so the pair is visible together.",
+ },
+ {
+ surface: "brain_recurrence",
+ kind: K.mcpTool,
+ category: C.excluded,
+ reason:
+ "swept in for file-level completeness: it shares procedure-tools.ts with " +
+ "brain_skill_proposals but reads only the recurrence ledger, whose entries are content " +
+ "hashes, scope names, support counts and source ids - no page path, title or body reaches " +
+ "this handler at all.",
},
{
surface: "brain_codegraph_report",
@@ -478,16 +568,20 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "search expand",
kind: K.cliVerb,
- category: C.excluded,
+ category: C.covered,
reason:
- "src/cli/search/verbs/expand.ts calls expandHit() directly - the same chunk_id hydration " +
- "brain_search_expand uses, with the same absence of a visibility check.",
+ "src/cli/search/verbs/expand.ts calls expandHit() directly - the same root-C chunk_id " +
+ "hydration brain_search_expand uses - and passes CLI_TRANSPORT_REACH, so the operator's own " +
+ "shell is answered in full by decision rather than by omission.",
},
{
surface: "brain backlinks",
kind: K.cliVerb,
- category: C.excluded,
- reason: "src/cli/brain/verbs/backlinks.ts calls buildBacklinkIndex, same as brain_backlinks.",
+ category: C.covered,
+ reason:
+ "src/cli/brain/verbs/backlinks.ts asks reachView about the target and every ref's source " +
+ "artifact, the same root-C decision brain_backlinks makes over the same index, at " +
+ "CLI_TRANSPORT_REACH - so the two mirrors cannot drift on what a ref discloses.",
},
{
surface: "brain bridges",
@@ -499,9 +593,12 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain clusters",
kind: K.cliVerb,
- category: C.excluded,
+ category: C.covered,
reason:
- "src/cli/brain/verbs/clusters.ts drives the same communities.ts core as brain_clusters.",
+ "src/cli/brain/verbs/clusters.ts reaches its input set through listVaultPages with " +
+ "CLI_TRANSPORT_REACH (root B) and readdirSyncs Brain/clusters for the listing, which the " +
+ "root-closure sweep registers as a direct vault read that discloses nothing beyond the " +
+ "operator's own shell.",
},
{
surface: "brain moc-audit",
@@ -514,10 +611,11 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain deep-synthesis",
kind: K.cliVerb,
- category: C.excluded,
+ category: C.covered,
reason:
- "src/cli/brain/verbs/deep-synthesis.ts drives the same mixed deepSynthesis() core as " +
- "brain_deep_synthesis.",
+ "src/cli/brain/verbs/deep-synthesis.ts calls deepSynthesis with CLI_TRANSPORT_REACH, which " +
+ "threads into search() exactly as the MCP tool does - covered transitively by root A, with " +
+ "the reach stated at the call site rather than defaulted.",
},
{
surface: "brain ideas",
@@ -535,12 +633,11 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain file-context",
kind: K.cliVerb,
- category: C.excluded,
+ category: C.covered,
reason:
- "src/cli/brain/verbs/file-context.ts calls fileContextRecall(), the same wrapper " +
- "brain_file_context uses - listed here as an entry of record even though the underlying " +
- "path is visibility-covered, so a reader of this registry does not have to cross-reference " +
- "the MCP list to learn the CLI verb's answer.",
+ "src/cli/brain/verbs/file-context.ts calls fileContextRecall with CLI_TRANSPORT_REACH, the " +
+ "same root-A path brain_file_context takes, so the CLI mirror and the MCP tool cannot drift " +
+ "on which pages a caller reaches.",
},
{
surface: "brain context-pack",
@@ -551,10 +648,12 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "brain query",
kind: K.cliVerb,
- category: C.excluded,
+ category: C.covered,
reason:
- "src/cli/brain/verbs/query.ts calls queryByPreference / queryByTopic, the same " +
- "visibility-blind Brain-record path brain_query uses.",
+ "src/cli/brain/verbs/query.ts passes CLI_TRANSPORT_REACH into QueryByTopicOptions, so the " +
+ "topic selection asks the same root-C rule brain_query asks. The verdict is admit-all " +
+ "because the caller is the operator's own shell, which is a decision this verb makes rather " +
+ "than a question it skips.",
},
{
surface: "brain sources",
@@ -648,34 +747,41 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
{
surface: "osb://preference/{id}",
kind: K.mcpResource,
- category: C.excluded,
+ category: C.covered,
reason:
- "gated by gatedOwnerScopeView (agent-scope), per resources.ts's own docblock on why the " +
- "four templated readers exist - a visibility-tagged preference page is returned in full, " +
- "frontmatter and body, once the owner-scope check passes.",
+ "root C, the key-addressed read: the whole file - frontmatter, owner line and body prose - " +
+ "is what this reader hands back, so both rules are asked before the read rather than " +
+ "filtered out of the bytes afterwards. A withheld preference is reported byte for byte as " +
+ "an absent one, because preference ids are pref-<topic-slug> and therefore guessable.",
},
{
surface: "osb://topic/{slug}",
kind: K.mcpResource,
- category: C.excluded,
+ category: C.covered,
reason:
- "same gatedOwnerScopeView-only path as osb://preference/{id}; visibility: is never read.",
+ "the same root-C view as osb://preference/{id}, with the reach reaching the SELECTION of the " +
+ "topic's current rule for the reason the owner scope already reached it: a topic resolves " +
+ "to one preference, so filtering afterwards would hide a readable rule whenever a reserved " +
+ "one happened to sort ahead of it.",
},
{
surface: "osb://log/{date}",
kind: K.mcpResource,
- category: C.excluded,
+ category: C.covered,
reason:
- "withVisibleLogEvents filters rendered log sections by gatedOwnerScopeView over the " +
- "artifacts each event names; no visibility check on those artifacts.",
+ "withVisibleLogEvents filters rendered log sections by every live rule over the artifacts " +
+ "each event names, reach included, through the shared artifact-ref view. A day with no rule " +
+ "live is returned verbatim - the split-and-rejoin is skipped entirely - so a vault the " +
+ "boundary admits in full stays byte-identical.",
},
{
surface: "osb://backlinks/{id}",
kind: K.mcpResource,
- category: C.excluded,
+ category: C.covered,
reason:
- "calls buildBacklinkIndex directly - resources.ts's own comment calls it 'the last " +
- "unscoped buildBacklinkIndex call in the product' - gated only by gatedOwnerScopeView.",
+ "the same reference-shaped root-C decision brain_backlinks makes, over the same index: the " +
+ "target and every ref's source artifact are both asked, and a withheld target answers with " +
+ "the empty backlink document rather than a refusal that would prove it exists.",
},
// --- Excluded: the index's own storage --------------------------------------
@@ -685,10 +791,16 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
category: C.excluded,
reason:
"chunker.ts's packBlocks emits a page's frontmatter block as its own chunk verbatim " +
- "(chunk_index 0), and the body as the chunks after it - indexer.ts applies no visibility " +
- "predicate anywhere in that pass, so a private page's full text, frontmatter included, is " +
- "stored in chunks and mirrored into chunk_fts regardless of any read-side filter. A copy of " +
- "the index carries the content a read-side filter only ever hides at query time.",
+ "(chunk_index 0), and the body as the chunks after it. A reserved page's full text is still " +
+ "stored in chunks and mirrored into chunk_fts, and this wave deliberately does not change " +
+ "that: excluding reserved pages from the index would take an operator's own private notes " +
+ "out of their own local search, which is a product regression dressed as a hardening. What " +
+ "DID change is that the indexer records what it measured of each page's declaration in " +
+ "documents.visibility, so the index is self-describing and search check can report the " +
+ "population it cannot measure. The column is not the read boundary - that is the live " +
+ "frontmatter check at the three roots, which reads the file rather than a snapshot of it - " +
+ "so anyone with file access to brain.sqlite still reads what the read side withholds, the " +
+ "same trust boundary the vault's own Markdown files have.",
},
]);
@@ -715,3 +827,89 @@ export function callableVisibilitySurfaces(): ReadonlyArray<VisibilitySurfaceEnt
export function excludedCallableVisibilitySurfaces(): ReadonlyArray<VisibilitySurfaceEntry> {
return callableVisibilitySurfaces().filter((entry) => entry.category === C.excluded);
}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Root closure: the files that read a vault path WITHOUT one of the roots
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Whether a direct vault read applies the boundary itself, or discloses
+ * nothing that needs it.
+ *
+ * The three read roots - `search()`'s pipeline, `listVaultPages`, and the
+ * key-addressed read primitives - are where the reserved-token rule is
+ * enforced, and the guarantee is only as good as the claim that every
+ * caller goes through one of them. A file that opens a vault path with
+ * `node:fs` directly is outside all three, so it either asks the rule on
+ * its own or has a written reason why the question does not arise.
+ */
+export const DIRECT_VAULT_READ_CATEGORY = Object.freeze({
+ /** Consults the reach rule itself, at the site of the read. */
+ guarded: "guarded",
+ /** Hands back nothing a page's reservation would cover. */
+ discloses_nothing: "discloses_nothing",
+} as const);
+
+export type DirectVaultReadCategory =
+ (typeof DIRECT_VAULT_READ_CATEGORY)[keyof typeof DIRECT_VAULT_READ_CATEGORY];
+
+export interface DirectVaultReadEntry {
+ /** Repo-relative path, exactly as the census spells it. */
+ readonly file: string;
+ readonly category: DirectVaultReadCategory;
+ /** What the category alone does not say - the source-verified argument. */
+ readonly reason: string;
+}
+
+const D = DIRECT_VAULT_READ_CATEGORY;
+
+/**
+ * Every file under `src/mcp/`, `src/cli/` and `src/openclaw/` that reads a
+ * vault path through `node:fs` rather than through one of the three roots,
+ * hand-verified against source.
+ *
+ * `tests/core/architecture/visibility-surface-census.test.ts` sweeps for
+ * the shape and fails in BOTH directions - an unregistered file, and a row
+ * naming a file that no longer reads that way - so this list cannot go
+ * quietly stale. What the sweep cannot see is stated in that file's
+ * docblock rather than implied here.
+ */
+export const DIRECT_VAULT_READ_REGISTRY: ReadonlyArray<DirectVaultReadEntry> = Object.freeze([
+ {
+ file: "src/mcp/brain/knowledge-tools.ts",
+ category: D.guarded,
+ reason:
+ "brain_clusters lists Brain/clusters/*.md with readdirSync and brain_bridges reads " +
+ "Brain/proposals/bridges.md with readFileSync, both by path and neither through a read " +
+ "root. Both now ask reachView(ctx.vault, contextReach(ctx)) about each path before its " +
+ "title or body crosses the boundary, which is the same decision isPathReadableAtReach " +
+ "makes for a ranked result.",
+ },
+ {
+ file: "src/cli/onboarding.ts",
+ category: D.discloses_nothing,
+ reason:
+ "countMarkdown readdirSyncs Brain/preferences and Brain/inbox and returns the LENGTH of " +
+ "the filtered list - no path, title or body leaves the function, and the caller is the " +
+ "operator's own shell, which the CLI already answers at local reach. A count of files in " +
+ "the operator's own Brain directory is not a disclosure to anyone else.",
+ },
+ {
+ file: "src/cli/brain/verbs/links.ts",
+ category: D.discloses_nothing,
+ reason:
+ "the link-repair verb readFileSyncs each page it is about to REWRITE and writes it back " +
+ "atomically. It is a maintenance lane in the operator's own shell, and one that must see " +
+ "every page: a repair that stopped reading reserved pages would rewrite the links around " +
+ "them and leave the graph pointing at nothing.",
+ },
+ {
+ file: "src/cli/brain/verbs/clusters.ts",
+ category: D.discloses_nothing,
+ reason:
+ "the CLI mirror of brain_clusters, readdirSyncing Brain/clusters for the staleness " +
+ "fast-path and the listing. It runs in the operator's own shell, which the CLI answers at " +
+ "local reach through CLI_TRANSPORT_REACH, so the reserved-token rule admits every page " +
+ "here by construction rather than by omission.",
+ },
+]);
diff --git a/src/core/vault.ts b/src/core/vault.ts
index 9287d418..7af6b687 100644
--- a/src/core/vault.ts
+++ b/src/core/vault.ts
@@ -64,6 +64,12 @@ import {
emitDegradationNotice,
} from "./integrity/degradation.ts";
import { vaultRelative } from "./path-safety.ts";
+import { type TransportReach } from "./graph/transport-reach.ts";
+import {
+ REMOTE_DENY_VISIBILITY_TOKEN,
+ isRemotelyReadable,
+ pageVisibility,
+} from "./graph/visibility.ts";
import type { FrontmatterMap, FrontmatterValue, VaultPage } from "./types.ts";
const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
@@ -556,7 +562,13 @@ export function extractWikilinks(content: string): string[] {
return result;
}
-export interface ListVaultPagesOptions {
+/**
+ * What every walker in this module accepts. Separate from
+ * {@link ListVaultPagesOptions} because only the walker that PARSES
+ * frontmatter can answer the visibility question, and a shared type would
+ * have let the cheap basename walkers claim an answer they cannot give.
+ */
+export interface VaultWalkOptions {
readonly skipDirs?: ReadonlyArray<string>;
readonly skipFiles?: ReadonlyArray<string>;
/**
@@ -575,25 +587,79 @@ export interface ListVaultPagesOptions {
readonly site?: string;
}
+export interface ListVaultPagesOptions extends VaultWalkOptions {
+ /**
+ * How far the caller of this walk reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`). REQUIRED, and deliberately so.
+ *
+ * This walker is one of the three roots every callable surface reaches
+ * page content through, and the two ways to get it wrong fail in
+ * opposite directions: a maintenance lane that quietly stopped seeing
+ * reserved pages would corrupt the link graph it repairs, while a read
+ * surface that quietly saw them would be the boundary failing. Neither
+ * is a decision to make by omission, so there is no default to inherit
+ * - every call site says which caller it is walking for.
+ */
+ readonly reach: TransportReach;
+}
+
const LIST_VAULT_PAGES_SITE = "vault.listVaultPages";
+/**
+ * The tag list a page whose file could not be read answers with: the
+ * reserved token, so a page nobody can measure is treated exactly as one
+ * that reserved itself. The twin of `UNMEASURABLE_VISIBILITY` in
+ * `core/search/result-filters.ts`, which makes the same substitution for
+ * roots A and C - spelled from the same exported token so the two cannot
+ * come to mean different things.
+ */
+const UNMEASURABLE_PAGE_VISIBILITY: ReadonlyArray<string> = Object.freeze([
+ REMOTE_DENY_VISIBILITY_TOKEN,
+]);
+
/**
* Walk the vault and return every Markdown page with parsed frontmatter
* metadata. Pages are sorted by title (case-insensitive). Excluded dirs/files
* mirror the Python defaults.
*
* Pass `opts.notices` to collect what the walk discarded β€” see
- * {@link ListVaultPagesOptions}.
+ * {@link VaultWalkOptions}.
+ *
+ * Root B of the visibility boundary: a page reserved against remote reads
+ * is dropped at {@link TRANSPORT_REACH.remote}, over the frontmatter this
+ * walk has already parsed, so a caller pays no extra read. The drop
+ * happens BEFORE the sort and before the array leaves this function, so
+ * no caller can count what it cannot see - a total that still included
+ * the withheld page would answer "there is one more page here than I am
+ * showing you". A vault that never wrote the token is byte-identical at
+ * both reaches.
+ *
+ * FAILS CLOSED on a page whose file could not be read, which is the one
+ * input the three roots must not disagree about. The parsed map resolves
+ * an unreadable file to `{}`, and reading that as "declares nothing"
+ * would admit at remote reach exactly the page
+ * {@link isPathReadableAtReach} denies for roots A and C - so the walk
+ * carries the read verdict beside the map (see {@link WalkedPage}) and
+ * substitutes {@link UNMEASURABLE_PAGE_VISIBILITY} for it, which is the
+ * same substitution those roots make.
*/
-export function listVaultPages(vaultDir: string, opts: ListVaultPagesOptions = {}): VaultPage[] {
+export function listVaultPages(vaultDir: string, opts: ListVaultPagesOptions): VaultPage[] {
const skipDirs = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
const skipFiles = new Set((opts.skipFiles ?? DEFAULT_SKIP_FILES).map((f) => f.toLowerCase()));
- const pages: VaultPage[] = [];
- walk(vaultDir, vaultDir, skipDirs, skipFiles, pages, {
+ const walked: WalkedPage[] = [];
+ walk(vaultDir, vaultDir, skipDirs, skipFiles, walked, {
sink: opts.notices,
site: opts.site ?? LIST_VAULT_PAGES_SITE,
});
+ const pages = walked
+ .filter((w) =>
+ isRemotelyReadable(
+ w.unreadable ? UNMEASURABLE_PAGE_VISIBILITY : pageVisibility(w.page.metadata),
+ opts.reach,
+ ),
+ )
+ .map((w) => w.page);
pages.sort((a, b) => a.title.toLowerCase().localeCompare(b.title.toLowerCase()));
return pages;
}
@@ -617,10 +683,7 @@ interface WalkNoticeSink {
* β€” and until now it was accepted and dropped, so a caller that asked
* where the walk went blind was answered with silence.
*/
-export function listVaultBasenames(
- vaultDir: string,
- opts: ListVaultPagesOptions = {},
-): Set<string> {
+export function listVaultBasenames(vaultDir: string, opts: VaultWalkOptions = {}): Set<string> {
return new Set(
listVaultNotePaths(vaultDir, {
...opts,
@@ -639,10 +702,7 @@ export function listVaultBasenames(
* before publishing the basename needs both, and deriving the path back
* from a basename is exactly the guess this project refuses.
*/
-export function listVaultNotePaths(
- vaultDir: string,
- opts: ListVaultPagesOptions = {},
-): Array<string> {
+export function listVaultNotePaths(vaultDir: string, opts: VaultWalkOptions = {}): Array<string> {
const skipDirs = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
const skipFiles = new Set((opts.skipFiles ?? DEFAULT_SKIP_FILES).map((f) => f.toLowerCase()));
const out: string[] = [];
@@ -699,12 +759,29 @@ function walkBasenames(
}
}
+/**
+ * A walked page plus the one fact the parsed map cannot carry: whether
+ * its file could be READ at all.
+ *
+ * {@link VaultPage.metadata} resolves an unreadable file to `{}`, which is
+ * byte-indistinguishable from a page that declares nothing - so root B
+ * would read an unreadable page as untagged and admit it, while roots A
+ * and C substitute the reserved token for exactly that state and deny it.
+ * Two spellings of one rule, disagreeing in the fail direction. Internal
+ * to this module: the flag exists to decide the walk's own filter, and
+ * `VaultPage` stays the shape every caller already consumes.
+ */
+interface WalkedPage {
+ readonly page: VaultPage;
+ readonly unreadable: boolean;
+}
+
function walk(
root: string,
dir: string,
skipDirs: Set<string>,
skipFiles: Set<string>,
- out: VaultPage[],
+ out: WalkedPage[],
notices: WalkNoticeSink,
): void {
let entries;
@@ -746,7 +823,12 @@ function walk(
if (notices.sink !== undefined) notices.sink.push(...pageNotices);
const titleVal = meta["title"];
const title = typeof titleVal === "string" && titleVal ? titleVal : stem(entry.name);
- out.push({ title, path: full, metadata: meta });
+ out.push({
+ page: { title, path: full, metadata: meta },
+ // The same verdict `readCachedFrontmatterEntry` carries for roots A
+ // and C, read off the notices this walk already produced.
+ unreadable: pageNotices.some((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable),
+ });
}
}
diff --git a/src/mcp/brain/hygiene-tools.ts b/src/mcp/brain/hygiene-tools.ts
index 800e35ca..a1d124b4 100644
--- a/src/mcp/brain/hygiene-tools.ts
+++ b/src/mcp/brain/hygiene-tools.ts
@@ -20,6 +20,9 @@
import { resolveAgentName } from "../../core/config.ts";
import { loadBrainConfig } from "../../core/brain/policy.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
+import { everyArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
+import { reachView } from "../../core/brain/reach-view.ts";
+import { contextReach } from "../tool-contract.ts";
import { applyHygienePlan } from "../../core/brain/hygiene/apply.ts";
import { buildHygienePlan } from "../../core/brain/hygiene/plan.ts";
import { resolveConflictFindings } from "../../core/brain/hygiene/resolve-conflicts.ts";
@@ -238,7 +241,16 @@ async function toolBrainHygiene(
// `unknown_ids` - would be an existence oracle over the same
// population the scan just refused to enumerate
// (`preferences-collect.ts` states the convention).
- const view = gatedOwnerScopeView(ctx.vault, ctx.agentName);
+ // Both rules, ANDed, on the seam the owner rule already sits on. The
+ // detectors walk with `MAINTENANCE_LANE_REACH` - correct for a scan
+ // that must see the whole vault it is diagnosing - so the reserved
+ // pages are deliberately walked IN, and this is where they stop. Adding
+ // the rule here rather than threading it through four detector
+ // signatures also means a detector added later inherits it.
+ const view = everyArtifactRefView(
+ gatedOwnerScopeView(ctx.vault, ctx.agentName),
+ reachView(ctx.vault, contextReach(ctx)),
+ );
const findings = view.keep(scanned.findings, (f) => findingRefs(ctx.vault, f));
const report: HygieneScanReport = Object.freeze({ ...scanned, findings });
diff --git a/src/mcp/brain/knowledge-tools.ts b/src/mcp/brain/knowledge-tools.ts
index 701075ca..c725dd89 100644
--- a/src/mcp/brain/knowledge-tools.ts
+++ b/src/mcp/brain/knowledge-tools.ts
@@ -37,6 +37,8 @@ import {
import { diarize, DiarizationError } from "../../core/brain/diarization.ts";
import { discoverIdeas, ideaCandidates } from "../../core/brain/idea-discovery.ts";
import { auditMoc, MocAuditError } from "../../core/brain/link-graph/moc-audit.ts";
+import { reachView } from "../../core/brain/reach-view.ts";
+import { everyArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { normaliseWikilinkTarget } from "../../core/brain/wikilink.ts";
import { isoSecond } from "../../core/brain/time.ts";
@@ -62,12 +64,24 @@ import {
type ClaimNode,
} from "../../core/brain/claim-graph.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import { contextReach } from "../tool-contract.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { AGENT_SCOPE_SCHEMA, coerceAgentScope, coerceStr, coerceBool } from "../coerce.ts";
import { coercePositiveInteger, toolSafeguard } from "./shared.ts";
+/**
+ * Vault-relative locations these two handlers read BY PATH, rather than
+ * through one of the three read roots. Named here because each was
+ * spelled twice - once to build the absolute path and once to report the
+ * relative one - and the two spellings had to agree for the boundary
+ * check below to be asking about the page it was returning.
+ */
+const BRAIN_CLUSTERS_REL = "Brain/clusters";
+const BRAIN_PROPOSALS_REL = "Brain/proposals";
+const BRIDGE_PROPOSALS_FILE = "bridges.md";
+
/** Forward-looking projection envelope; read-only fold. */
function toolBrainForesight(
ctx: ServerContext,
@@ -139,12 +153,19 @@ async function toolBrainBridges(
}
}
if (op === "list") {
- const path = join(ctx.vault, "Brain", "proposals", "bridges.md");
- if (!existsSync(path)) return { exists: false, proposals: 0 };
+ const rel = join(BRAIN_PROPOSALS_REL, BRIDGE_PROPOSALS_FILE);
+ const path = join(ctx.vault, rel);
+ // Root closure: this reads a vault page BY PATH without going through
+ // one of the three read roots, so it asks the rule here. A reserved
+ // proposals page answers exactly as an absent one - the same shape
+ // the by-path read primitives hold.
+ if (!existsSync(path) || !reachView(ctx.vault, contextReach(ctx)).visible(rel)) {
+ return { exists: false, proposals: 0 };
+ }
const [meta] = parseFrontmatter(path);
return {
exists: true,
- path: "Brain/proposals/bridges.md",
+ path: rel,
generated_at: meta["generated_at"] ?? null,
proposals: Number(meta["proposals"] ?? 0),
};
@@ -194,12 +215,25 @@ async function toolBrainBridges(
} catch {
// Metrics are observability, not correctness.
}
+ // Root closure over what the CALLER is told. Detection stays
+ // vault-wide - a bridge proposed from the visible half of a link
+ // graph would differ per caller and the proposals are written to one
+ // shared artifact - so the walk is unfiltered, the write is
+ // unfiltered, and the response is not. A proposal names two pages by
+ // path, so one withheld end withholds the proposal WHOLE: a bridge
+ // reported with one end missing is not a narrower true finding but a
+ // false one. `scanned_candidates` is a corpus size that names nothing
+ // and is the same number at every reach, so it stays as measured.
+ //
+ // `list` reads the artifact this branch just wrote, and asks the rule
+ // over the FILE - which is why writing it unfiltered is safe here.
+ const view = reachView(ctx.vault, contextReach(ctx));
return {
vec_available: report.vecAvailable,
...(report.reason !== undefined ? { reason: report.reason } : {}),
scanned_candidates: report.scannedCandidates,
- proposals: report.proposals,
- artifact: "Brain/proposals/bridges.md",
+ proposals: report.proposals.filter((p) => view.row(p.source, p.target)),
+ artifact: join(BRAIN_PROPOSALS_REL, BRIDGE_PROPOSALS_FILE),
};
} finally {
await store.close();
@@ -219,16 +253,23 @@ async function toolBrainClusters(
throw new MCPError(INVALID_PARAMS, "brain_clusters: operation must be run|list");
}
if (op === "list") {
- const dir = join(ctx.vault, "Brain", "clusters");
+ const dir = join(ctx.vault, BRAIN_CLUSTERS_REL);
if (!existsSync(dir)) return { clusters: [] };
+ // Root closure: a directory listing by path, outside the three read
+ // roots, so the rule is asked per page here. A withheld cluster is
+ // dropped and nothing counts it - the caller cannot tell this listing
+ // from one over a vault that never held the page.
+ const view = reachView(ctx.vault, contextReach(ctx));
const clusters = readdirSync(dir)
.filter((f) => f.endsWith(".md"))
.toSorted()
.map((f) => {
+ const rel = join(BRAIN_CLUSTERS_REL, f);
+ if (!view.visible(rel)) return null;
const [meta] = parseFrontmatter(join(dir, f));
return meta["kind"] === "brain-cluster"
? {
- path: `Brain/clusters/${f}`,
+ path: rel,
cluster: String(meta["cluster"] ?? ""),
size: Number(meta["size"] ?? 0),
density: Number(meta["density"] ?? 0),
@@ -300,7 +341,16 @@ async function toolBrainClusters(
// visible half of a link graph would produce different communities
// for every caller and write them over each other. This filters what
// the CALLER is told, which is the boundary the gate declares.
- const view = gatedOwnerScopeView(ctx.vault, ctx.agentName);
+ // Both rules, ANDed: a community naming a page EITHER rule withholds
+ // is dropped whole. The reserved-token half arrived with the read
+ // roots; the argument above for dropping rather than trimming is the
+ // same for it, and detection stays vault-wide for the same reason -
+ // clustering the visible half of a link graph would produce different
+ // communities per caller and write them over each other.
+ const view = everyArtifactRefView(
+ gatedOwnerScopeView(ctx.vault, ctx.agentName),
+ reachView(ctx.vault, contextReach(ctx)),
+ );
const visible = view.keep(communities, (c) => c.members.map((m) => m.path));
// `written` / `removed` are the cluster NOTES, and a cluster note is
// named `cluster-<community id>.md` after the seed page - so its own
@@ -318,11 +368,11 @@ async function toolBrainClusters(
})),
written: materialized.written.filter((p) => visibleNotes.has(p)),
// A removal names a community that no longer exists, so there is
- // no surviving membership to ask about. Under a scope the list is
- // withheld whole: it is the one field here whose subject cannot be
- // resolved, and a `removed` entry naming a hidden seed is the same
- // disclosure as a `written` one.
- removed: view.scope === null ? materialized.removed : [],
+ // no surviving membership to ask about. Whenever ANY rule is live
+ // the list is withheld whole: it is the one field here whose
+ // subject cannot be resolved, and a `removed` entry naming a hidden
+ // seed is the same disclosure as a `written` one.
+ removed: view.filtersNothing ? materialized.removed : [],
...(materialized.batches ? { batches: materialized.batches } : {}),
};
} finally {
@@ -393,6 +443,7 @@ async function toolBrainDeepSynthesis(
now,
limit,
...(agentScope !== undefined ? { agentScope } : {}),
+ transportReach: contextReach(ctx),
});
let triggersCreated: number | undefined;
if (enqueue) {
diff --git a/src/mcp/brain/procedure-tools.ts b/src/mcp/brain/procedure-tools.ts
index 7de69f77..51d674cc 100644
--- a/src/mcp/brain/procedure-tools.ts
+++ b/src/mcp/brain/procedure-tools.ts
@@ -36,6 +36,8 @@ import {
purgeRecurrenceSource,
} from "../../core/brain/recurrence.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import { contextReach } from "../tool-contract.ts";
+import { reachView } from "../../core/brain/reach-view.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { coerceStrList } from "../coerce.ts";
import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
@@ -86,10 +88,22 @@ async function toolBrainSkillProposals(
...(ctx.repoRoot ? { repoRoot: ctx.repoRoot } : {}),
...(skillsDir !== null ? { skillsDir } : {}),
});
+ // `planSkillPageDrafts` walks with `MAINTENANCE_LANE_REACH`, which is
+ // right for a plan that has to see the whole vault it is proposing
+ // over - and wrong to hand to a caller unfiltered, because both lists
+ // report a page's path and title and `skipped` adds a `detail` about
+ // it. The rule is asked here, over what the caller is told.
+ //
+ // `pages_scanned` is recomputed from the visible lists for the same
+ // reason `brain_hygiene` recomputes its counts: a corpus size taken
+ // before the filter states how many pages were withheld.
+ const view = reachView(ctx.vault, contextReach(ctx));
+ const admitted = report.admitted.filter((c) => view.visible(c.path));
+ const skipped = report.skipped.filter((s) => view.visible(s.path));
return {
generated_at: report.generatedAt,
- pages_scanned: report.pagesScanned,
- admitted: report.admitted.map((c) => ({
+ pages_scanned: view.filtersNothing ? report.pagesScanned : admitted.length + skipped.length,
+ admitted: admitted.map((c) => ({
path: c.path,
title: c.title,
tier: c.tier,
@@ -99,7 +113,7 @@ async function toolBrainSkillProposals(
reuse_observations: c.reuseObservations,
llm_step: c.llmStep,
})),
- skipped: report.skipped.map((s) => ({
+ skipped: skipped.map((s) => ({
path: s.path,
title: s.title,
reason: s.reason,
diff --git a/src/mcp/brain/query-tools.ts b/src/mcp/brain/query-tools.ts
index f99fa064..99cbbd5a 100644
--- a/src/mcp/brain/query-tools.ts
+++ b/src/mcp/brain/query-tools.ts
@@ -29,6 +29,7 @@ import {
} from "../../core/brain/types.ts";
import type { BrainLogEntry } from "../../core/brain/log.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import { contextReach } from "../tool-contract.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
@@ -51,6 +52,8 @@ import {
import { loadGuardrailsConfigSafe } from "../../core/brain/policy.ts";
import { normalizeAgentScope } from "../../core/graph/agent-scope.ts";
import { isPreferenceVisible } from "../../core/brain/owner-scoped-facts.ts";
+import { reachView } from "../../core/brain/reach-view.ts";
+import { logEntryArtifactRefs } from "../../core/brain/log.ts";
/** Accepted `at` forms, named in every refusal so the exit is actionable. */
const AS_OF_FORMS = "an ISO-8601 instant or YYYY-MM-DD date";
@@ -147,6 +150,11 @@ async function toolBrainQuery(
? normalizeAgentScope(requestedScope)
: null;
+ // Root C's rule over the reference-shaped rows this tool returns:
+ // a signal, a log event and a preference each NAME an artifact, and a
+ // row naming one the caller may not see discloses it by naming it.
+ const queryView = reachView(ctx.vault, contextReach(ctx));
+
const startedAtMs = Date.now();
const emitQueryTelemetry = (status: "ok" | "empty" | "error", resultCount: number): void => {
// Lazy emit kernel (t_5d7aa7c5): gate off = thunk never runs; a
@@ -175,8 +183,19 @@ async function toolBrainQuery(
// retired record is read through the same predicate as an active
// one - retiring a memory must not publish it.
const prefOwner = res.preference.owner;
+ // Both refusals carry the CALLER'S OWN ARGUMENT, which is what
+ // `queryByPreference` throws for a preference that does not
+ // exist. `BrainNotFoundError` formats the sentence itself, so
+ // passing a sentence to it produced "...found for id 'preference
+ // not found: pref-x'" against the absent form's "...for id
+ // 'pref-x'" - two messages, over a `pref-<slug>` key space a
+ // caller can enumerate, which is exactly the existence oracle the
+ // comment claimed was closed.
if (ownerScope !== null && !isPreferenceVisible({ owner: prefOwner }, ownerScope)) {
- throw new BrainNotFoundError(`preference not found: ${preference}`);
+ throw new BrainNotFoundError(preference);
+ }
+ if (!queryView.visible(res.preference.id)) {
+ throw new BrainNotFoundError(preference);
}
emitQueryTelemetry(res.evidence.length > 0 ? "ok" : "empty", res.evidence.length);
return {
@@ -199,9 +218,17 @@ async function toolBrainQuery(
const showExpired = coerceBoolOptional(args, "show_expired") ?? false;
const res = queryByTopic(ctx.vault, topic, {
showExpired,
+ transportReach: contextReach(ctx),
...(asOf !== null ? { now: asOf } : {}),
});
- const resultCount = res.signals.length + res.all_log_events.length;
+ // Filter BEFORE the count, as the `since` branch below does. The
+ // count is written to the vault's recall-telemetry log and handed
+ // back verbatim by `brain_recall_telemetry`, so a pre-filter number
+ // tells the caller how many rows it was not shown - a count oracle
+ // reached through a second tool rather than this one.
+ const signals = queryView.keep(res.signals, (sig) => [sig.id]);
+ const logEvents = queryView.keep(res.all_log_events, (e) => logEntryArtifactRefs(e));
+ const resultCount = signals.length + logEvents.length;
emitQueryTelemetry(resultCount > 0 ? "ok" : "empty", resultCount);
const topicPrefOwner = res.preference?.owner;
const topicPrefVisible =
@@ -211,19 +238,20 @@ async function toolBrainQuery(
return {
mode: "topic",
topic,
- signals: res.signals.map(serializeSignal),
+ signals: signals.map(serializeSignal),
preference: topicPrefVisible ? serializePreference(res.preference!) : null,
- all_log_events: res.all_log_events.map(serializeLogEntry),
+ all_log_events: logEvents.map(serializeLogEntry),
};
}
// since
const res = queryByLogSince(ctx.vault, since!);
- emitQueryTelemetry(res.length > 0 ? "ok" : "empty", res.length);
+ const events = queryView.keep(res, (e) => logEntryArtifactRefs(e));
+ emitQueryTelemetry(events.length > 0 ? "ok" : "empty", events.length);
return {
mode: "since",
since: since!.toISOString(),
- events: res.map(serializeLogEntry),
+ events: events.map(serializeLogEntry),
};
} catch (exc) {
emitQueryTelemetry("error", 0);
@@ -327,7 +355,19 @@ async function toolBrainBacklinks(
// (a-label-is-not-a-boundary, U3). The scope is the gated one: no
// argument exists on this tool, and under `off` the view hides nothing.
const index = buildBacklinkIndex(ctx.vault, gatedOwnerScopeView(ctx.vault, ctx.agentName).scope);
- const refs = index.get(target) ?? [];
+ // The same reasoning one rule over: a ref names the artifact that WROTE
+ // it, so an index unfiltered by reach publishes the id of a page
+ // reserved against remote reads. A withheld TARGET answers as an absent
+ // one - the empty backlink document - rather than refusing, because an
+ // unknown target is a legitimate zero here and a refusal would be the
+ // one response shape that proves the page exists.
+ const view = reachView(ctx.vault, contextReach(ctx));
+ const refs = view.visible(target)
+ ? (index.get(target) ?? []).filter((r) => view.visible(r.source))
+ : [];
+ const unparsed = index.unparsed
+ .filter((u) => view.visible(u.source))
+ .map((u) => ({ source: u.source, source_kind: u.sourceKind, reason: u.reason }));
return {
id: target,
count: refs.length,
@@ -340,17 +380,15 @@ async function toolBrainBacklinks(
// A `count` beside a non-empty `unparsed` is not a measurement: the
// walk skipped artifacts whose references it could not read, and a
// caller told only the count would read a legacy vault's zero as a
- // genuine zero. Omitted entirely when the walk was clean, so a
- // healthy vault's payload is byte-identical.
- ...(index.unparsed.length > 0
- ? {
- unparsed: index.unparsed.map((u) => ({
- source: u.source,
- source_kind: u.sourceKind,
- reason: u.reason,
- })),
- }
- : {}),
+ // genuine zero. Omitted entirely when the walk is clean, so a healthy
+ // vault's payload is byte-identical.
+ //
+ // Filtered by the same rule the refs are. Each entry NAMES its source
+ // artifact by id, so an unfiltered list disclosed a reserved page's id
+ // through a call that never mentioned it - and the honesty this field
+ // exists for does not extend to being honest about pages the caller
+ // may not know exist.
+ ...(unparsed.length > 0 ? { unparsed } : {}),
};
}
diff --git a/src/mcp/brain/recall-tools.ts b/src/mcp/brain/recall-tools.ts
index 18b78aa0..3f87c4a5 100644
--- a/src/mcp/brain/recall-tools.ts
+++ b/src/mcp/brain/recall-tools.ts
@@ -73,6 +73,7 @@ import { aggregateQueryDemand, serializeQueryDemandReport } from "../../core/bra
import { buildRetrievalPlan, serializeRetrievalPlan } from "../../core/brain/retrieval-plan.ts";
import { isoSecond } from "../../core/brain/time.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import { contextReach } from "../tool-contract.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
@@ -106,6 +107,10 @@ async function toolBrainBenchmark(
const report = await runRecallBenchmark(searchConfig, dataset, {
...(k !== undefined ? { k: k as number } : {}),
expand: args["expand"] === true,
+ // The dataset is the caller's, and so is the reach it is scored at:
+ // `hit` / `rank` / `expectedFound` for caller-named paths is an
+ // existence oracle over any corpus the caller did not earn.
+ transportReach: contextReach(ctx),
});
try {
appendMetric(ctx.vault, {
@@ -171,6 +176,9 @@ async function toolBrainTune(
const report = await tuneRecall(searchConfig, dataset, {
...(k !== undefined ? { k: k as number } : {}),
now,
+ // Same reasoning as `brain_benchmark`: the grid is scored with the
+ // benchmark, so every cell inherits whatever reach is passed here.
+ transportReach: contextReach(ctx),
});
try {
appendMetric(ctx.vault, {
diff --git a/src/mcp/http.ts b/src/mcp/http.ts
index c23b15a5..3c24ed4d 100644
--- a/src/mcp/http.ts
+++ b/src/mcp/http.ts
@@ -29,6 +29,7 @@ import { errorResponse, type JsonRpcResponse } from "./server.ts";
import { INTERNAL_ERROR, INVALID_REQUEST, PARSE_ERROR } from "./protocol.ts";
import { DRAIN_STATE, RequestDrain, resolveDrainDeadlineMs, type DrainOutcome } from "./drain.ts";
import { ORIGIN_CHANNEL, setOriginChannel } from "../core/origin-channel.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../core/graph/transport-reach.ts";
export interface ServeHttpOptions {
readonly host?: string;
@@ -47,6 +48,8 @@ export interface HttpServerHandle {
readonly host: string;
readonly port: number;
readonly url: string;
+ /** The reach this bind minted for every request it will carry. */
+ readonly reach: TransportReach;
/** The in-flight register, so a caller can report what is running. */
readonly drain: RequestDrain;
/**
@@ -79,7 +82,11 @@ export async function startHttp(
);
}
const port = opts.port ?? 0;
- const mcp = new MCPServer(ctx, runtimeOpts);
+ // A transport fact, set after the caller's runtime options for the same
+ // reason `sendNotification` is on stdio: a runtime option must not be
+ // able to claim a reach this bind did not establish.
+ const reach = httpBindReach(host);
+ const mcp = new MCPServer(ctx, { ...runtimeOpts, reach });
const drain = new RequestDrain();
const deadlineMs = opts.drainDeadlineMs ?? resolveDrainDeadlineMs(process.env);
const server = createServer(async (req, res) => {
@@ -140,6 +147,7 @@ export async function startHttp(
host,
port: actualPort,
url: `http://${host}:${actualPort}`,
+ reach,
drain,
close: () => closeHttp(server, drain, deadlineMs, sockets),
};
@@ -335,6 +343,22 @@ function authorized(req: IncomingMessage, apiKey: string): boolean {
/** Canonical loopback host names a rebinding guard trusts. */
const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+/**
+ * What an HTTP bind on `host` establishes about the callers it will
+ * accept: nothing beyond "a request arrived", unless the bind is
+ * loopback - in which case the request originated on this host.
+ *
+ * Keyed on the BIND rather than on a per-request peer address, because
+ * that is what this transport actually controls: a non-loopback bind is
+ * an explicit decision to expose the Brain on the network, and it already
+ * carries a mandatory bearer (see {@link startHttp}). A `Host` header is
+ * a caller-supplied string and could not be used here for the reason
+ * `./reach-refusal.ts` states.
+ */
+export function httpBindReach(host: string): TransportReach {
+ return isLoopbackHost(host) ? TRANSPORT_REACH.local : TRANSPORT_REACH.remote;
+}
+
export function isLoopbackHost(host: string): boolean {
return LOOPBACK_HOSTS.has(normaliseHostname(host));
}
diff --git a/src/mcp/reach-refusal.ts b/src/mcp/reach-refusal.ts
new file mode 100644
index 00000000..3fb91bf7
--- /dev/null
+++ b/src/mcp/reach-refusal.ts
@@ -0,0 +1,106 @@
+/**
+ * Why a caller-supplied transport reach is REFUSED instead of honoured.
+ *
+ * The reach a request arrived at decides whether a page reserved against
+ * remote reads may be answered (`src/core/graph/transport-reach.ts`). It
+ * is minted by the transport, because the transport is the only party
+ * that holds the fact - and the moment a caller could name it, the
+ * boundary would be a request parameter and the reservation would mean
+ * nothing.
+ *
+ * This is the same rule `./owner-scope-refusal.ts` states once for owner
+ * identity, applied to reach: an identity - or a trust level - echoed
+ * back from the request is not one. Refused rather than silently ignored,
+ * because a dropped argument answers a question nobody asked; refused
+ * rather than narrowed behind the caller's back, because the caller would
+ * then believe it had read what it asked for.
+ *
+ * The rule does NOT depend on a tool's schema. `./argument-guard.ts`
+ * refuses arguments a CLOSED schema does not declare, which would already
+ * cover most of this - but only for the closed ones, and only with a
+ * message about a typo. A reach arriving from a caller is not a typo, and
+ * the surfaces that would be worth attacking are exactly the ones a
+ * future open schema would leave uncovered.
+ *
+ * Comparison is over a normalised name (case-folded, separators dropped),
+ * so `reach`, `Reach`, `transport_reach`, `transport-reach` and
+ * `transportReach` are one argument rather than five holes. `disclosure`
+ * is deliberately NOT reserved: it is the progressive result-depth mode
+ * on the recall surfaces and has nothing to do with this boundary.
+ */
+
+import { INVALID_PARAMS, MCPError } from "./protocol.ts";
+import type { ToolDefinition } from "./tool-contract.ts";
+
+/** The refusal token, named in the message and carried in `data`. */
+export const REACH_REFUSAL = "caller-supplied-reach";
+
+/**
+ * The argument names this server will not read a reach from, in their
+ * canonical spelling. Every case and separator variant of these normalises
+ * onto the same key - see {@link normalizeArgumentName}.
+ */
+export const RESERVED_REACH_ARGUMENTS: ReadonlyArray<string> = Object.freeze([
+ "reach",
+ "transport_reach",
+]);
+
+/** Case-folded, separator-free form, so one name is not five holes. */
+function normalizeArgumentName(name: string): string {
+ return name.normalize("NFC").toLowerCase().replaceAll(/[_-]/g, "");
+}
+
+const RESERVED_KEYS: ReadonlySet<string> = new Set(
+ RESERVED_REACH_ARGUMENTS.map(normalizeArgumentName),
+);
+
+/** The structured payload attached to the refusal, for machine callers. */
+export interface CallerSuppliedReachData {
+ readonly tool: string;
+ /** The caller's own spellings, in the caller's own key order. */
+ readonly refused_arguments: ReadonlyArray<string>;
+ readonly reserved_argument_names: ReadonlyArray<string>;
+}
+
+/**
+ * Every argument the caller sent that names the transport reach, in the
+ * caller's own spelling and key order. Empty is the ordinary case.
+ */
+export function findCallerSuppliedReach(args: Record<string, unknown>): ReadonlyArray<string> {
+ return Object.freeze(
+ Object.keys(args).filter((k) => RESERVED_KEYS.has(normalizeArgumentName(k))),
+ );
+}
+
+/** What the caller is told to do instead, once, so the fix is in hand. */
+const MINTING_RULE =
+ "the transport that accepted this request mints it - stdio and the CLI run inside a " +
+ "process the caller already started on this host, and an HTTP bind mints it from whether " +
+ "that bind is loopback";
+
+/**
+ * Refuse a call carrying a reach-shaped argument.
+ *
+ * Runs BEFORE the unknown-argument gate on the same seam, so a caller
+ * naming the boundary is told about the boundary rather than offered a
+ * spelling suggestion for it.
+ */
+export function assertNoCallerSuppliedReach(
+ tool: ToolDefinition,
+ args: Record<string, unknown>,
+): void {
+ const refused = findCallerSuppliedReach(args);
+ if (refused.length === 0) return;
+ const noun = refused.length === 1 ? "argument" : "arguments";
+ const message =
+ `${tool.name}: ${noun} ${refused.map((n) => `'${n}'`).join(", ")} refused ` +
+ `(${REACH_REFUSAL}): the transport reach is never read from a request, because a trust ` +
+ `claim echoed back from the caller is not a trust claim. Instead, ${MINTING_RULE}. ` +
+ `Remove the ${noun}; there is no request-side way to widen what this transport established.`;
+ const data: CallerSuppliedReachData = Object.freeze({
+ tool: tool.name,
+ refused_arguments: refused,
+ reserved_argument_names: RESERVED_REACH_ARGUMENTS,
+ });
+ throw new MCPError(INVALID_PARAMS, message, data);
+}
diff --git a/src/mcp/resources.ts b/src/mcp/resources.ts
index 942208bc..bdd45156 100644
--- a/src/mcp/resources.ts
+++ b/src/mcp/resources.ts
@@ -79,10 +79,13 @@ import {
validateSlug,
} from "../core/brain/paths.ts";
import { BrainNotFoundError, queryByPreference, queryByTopic } from "../core/brain/query.ts";
-import { gatedOwnerScopeView, type OwnerScopeView } from "../core/brain/owner-scope-view.ts";
+import { gatedOwnerScopeView } from "../core/brain/owner-scope-view.ts";
+import { everyArtifactRefView, type ArtifactRefView } from "../core/brain/artifact-ref-view.ts";
+import { reachView } from "../core/brain/reach-view.ts";
+import { resolvedTransportReach, type TransportReach } from "../core/graph/transport-reach.ts";
import { extractWikilinkRichBodies } from "../core/brain/link-graph/parse-wikilink.ts";
import { normaliseWikilinkTarget } from "../core/brain/wikilink.ts";
-import type { BrainLogEntry } from "../core/brain/log.ts";
+import { logEntryArtifactRefs } from "../core/brain/log.ts";
import type { BrainPreference, BrainRetired } from "../core/brain/types.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";
@@ -102,6 +105,17 @@ export interface ResourceContext {
* surfaces cannot disagree about what an unidentified caller sees.
*/
readonly agentName?: string | undefined;
+ /**
+ * How far the caller of this read reached, minted by the transport
+ * (`src/core/graph/transport-reach.ts`) and threaded from
+ * `MCPServer.reach` exactly as {@link ResourceContext.agentName} is
+ * threaded from `MCPServer.agentName`.
+ *
+ * Optional on the TYPE and mandatory in EFFECT, on the same terms
+ * `ServerContext.reach` is: absent means no transport established
+ * anything, which resolves to the narrowest rather than the widest.
+ */
+ readonly reach?: TransportReach;
}
export interface ResourceDescriptor {
@@ -206,25 +220,53 @@ export function readResource(ctx: ResourceContext, uri: string): ResourceContent
case "status":
return readStatus(ctx, uri);
case "preference":
- return readPreference(ctx, uri, parsed.id, ownerView(ctx));
+ return readPreference(ctx, uri, parsed.id, requestView(ctx));
case "topic":
- return readTopic(ctx, uri, parsed.slug, ownerView(ctx));
+ return readTopic(ctx, uri, parsed.slug, requestView(ctx));
case "log":
- return readLog(ctx, uri, parsed.date, ownerView(ctx));
+ return readLog(ctx, uri, parsed.date, requestView(ctx));
case "backlinks":
- return readBacklinks(ctx, uri, parsed.id, ownerView(ctx));
+ return readBacklinks(ctx, uri, parsed.id, requestView(ctx));
}
}
/**
- * The ownership rule bound to this request, built once per read.
+ * Both rules bound to this request, built once per read.
*
* Constructed at the switch rather than inside each reader so a reader
* added later cannot be the one that forgot: the four templated cases
* pass it explicitly and the compiler requires it.
+ *
+ * The two are ANDed rather than folded: ownership and reserved-token
+ * visibility are independent questions with independent answers, and a
+ * row survives only when both keep it. Which one dropped it is not
+ * observable, because neither reports a count - see
+ * `src/core/brain/artifact-ref-view.ts`.
+ */
+function requestView(ctx: ResourceContext): RequestView {
+ const owner = gatedOwnerScopeView(ctx.vault, ctx.agentName);
+ const reach = reachView(ctx.vault, resolvedTransportReach(ctx.reach));
+ return Object.freeze({
+ ownerScope: owner.scope,
+ reach: reach.reach,
+ refs: everyArtifactRefView(owner, reach),
+ });
+}
+
+/**
+ * The two rules this request is answered under.
+ *
+ * `refs` is the ANDed decision every reference-shaped filter asks.
+ * `ownerScope` is separate because two readers push ownership into their
+ * SELECTION rather than filtering afterwards - `queryByTopic` and
+ * `buildBacklinkIndex` both take a scope - and that argument is the owner
+ * rule's alone. The reserved-token rule has no selection-side form; it is
+ * asked over the rows those selections return.
*/
-function ownerView(ctx: ResourceContext): OwnerScopeView {
- return gatedOwnerScopeView(ctx.vault, ctx.agentName);
+interface RequestView {
+ readonly ownerScope: string | null;
+ readonly reach: TransportReach;
+ readonly refs: ArtifactRefView;
}
/**
@@ -352,7 +394,7 @@ function readPreference(
ctx: ResourceContext,
uri: string,
rawId: string,
- view: OwnerScopeView,
+ view: RequestView,
): ResourceContent {
if (!rawId.trim()) {
throw new MCPError(INVALID_PARAMS, `resource id must not be empty: ${uri}`);
@@ -398,7 +440,15 @@ function readPreference(
// The whole file, `owner:` line and body prose included, is what this
// reader hands back - so the ownership question is asked before the
// read, not filtered out of the bytes afterwards.
- if (!view.visible(resolvedId)) throw notFound(rawId);
+ //
+ // `normalized`, not `rawId`: the absent branch above rethrows what
+ // `queryByPreference` threw, and that names the NORMALISED id. This
+ // reader accepts the bare slug too, so echoing the raw one here made
+ // `osb://preference/acme` answer "...for id 'acme'" when the page
+ // existed and was withheld, against "...for id 'pref-acme'" when it did
+ // not - the presence of the prefix a one-bit existence oracle over the
+ // whole reserved population.
+ if (!view.refs.visible(resolvedId)) throw notFound(normalized);
return readMarkdown(uri, filePath);
}
@@ -406,7 +456,7 @@ function readTopic(
ctx: ResourceContext,
uri: string,
rawSlug: string,
- view: OwnerScopeView,
+ view: RequestView,
): ResourceContent {
if (!rawSlug.trim()) {
throw new MCPError(INVALID_PARAMS, `topic slug must not be empty: ${uri}`);
@@ -418,7 +468,10 @@ function readTopic(
// to one preference and several may carry it, so filtering afterwards
// would report the topic as having no rule whenever another owner's
// preference happened to sort first.
- result = queryByTopic(ctx.vault, rawSlug, { ownerScope: view.scope });
+ result = queryByTopic(ctx.vault, rawSlug, {
+ ownerScope: view.ownerScope,
+ transportReach: view.reach,
+ });
} catch (err) {
if (err instanceof BrainNotFoundError) {
throw new MCPError(INTERNAL_ERROR, err.message);
@@ -433,8 +486,8 @@ function readTopic(
// already has that shape for a topic that never reached promotion.
const scoped = Object.freeze({
...result,
- signals: view.keep(result.signals, (s) => [s.id]),
- all_log_events: view.keep(result.all_log_events, (e) => logEventRefs(e)),
+ signals: view.refs.keep(result.signals, (s) => [s.id]),
+ all_log_events: view.refs.keep(result.all_log_events, (e) => logEntryArtifactRefs(e)),
});
return {
uri,
@@ -443,26 +496,11 @@ function readTopic(
};
}
-/**
- * Every artifact one log entry would name, as the owner-scope view
- * spells references.
- *
- * A log body is an untyped payload record; the fields that carry an
- * artifact are the wikilink-shaped ones, and the view unbrackets them
- * itself. `path` is the vault-relative page the event was about.
- */
-function logEventRefs(entry: BrainLogEntry): ReadonlyArray<string | undefined> {
- const body = (entry.body ?? {}) as Record<string, unknown>;
- const field = (key: string): string | undefined =>
- typeof body[key] === "string" ? (body[key] as string) : undefined;
- return [field("path"), field("preference"), field("signal"), field("artifact")];
-}
-
function readLog(
ctx: ResourceContext,
uri: string,
rawDate: string,
- view: OwnerScopeView,
+ view: RequestView,
): ResourceContent {
validateIsoDate(rawDate);
// Per-device shards (Memory Integrity Suite): a day's human view can
@@ -474,7 +512,7 @@ function readLog(
throw new MCPError(INTERNAL_ERROR, `no log file for date '${rawDate}'`);
}
const shard = (f: { path: string }): string =>
- withVisibleLogEvents(readFileSync(f.path, "utf8"), view);
+ withVisibleLogEvents(readFileSync(f.path, "utf8"), view.refs);
// The single-shard read stays verbatim (trailing newline included), so
// a vault with the gate off is byte-identical to the pre-filter shape.
if (files.length === 1) return { uri, mimeType: MIME_MARKDOWN, text: shard(files[0]!) };
@@ -500,8 +538,8 @@ const LOG_EVENT_HEADING = "\n## ";
* event, and the wikilink / `.md` path tokens inside the section - not a
* match on any event's prose.
*/
-function withVisibleLogEvents(markdown: string, view: OwnerScopeView): string {
- if (view.scope === null) return markdown;
+function withVisibleLogEvents(markdown: string, view: ArtifactRefView): string {
+ if (view.filtersNothing) return markdown;
const parts = markdown.split(LOG_EVENT_HEADING);
const head = parts[0]!;
const kept = parts
@@ -524,7 +562,7 @@ function readBacklinks(
ctx: ResourceContext,
uri: string,
rawId: string,
- view: OwnerScopeView,
+ view: RequestView,
): ResourceContent {
if (!rawId.trim()) {
throw new MCPError(INVALID_PARAMS, `backlinks target must not be empty: ${uri}`);
@@ -542,8 +580,10 @@ function readBacklinks(
// not-found path at all (an unknown target is a legitimate zero), so a
// refusal here would be the one response shape that proves the page
// exists. The echoed target is the caller's own argument.
- const index = buildBacklinkIndex(ctx.vault, view.scope);
- const refs = view.visible(target) ? (index.get(target) ?? []) : [];
+ const index = buildBacklinkIndex(ctx.vault, view.ownerScope);
+ const refs = view.refs.visible(target)
+ ? (index.get(target) ?? []).filter((ref) => view.refs.visible(ref.source))
+ : [];
return {
uri,
mimeType: MIME_MARKDOWN,
diff --git a/src/mcp/search-tools.ts b/src/mcp/search-tools.ts
index 7cc70c92..31be29a7 100644
--- a/src/mcp/search-tools.ts
+++ b/src/mcp/search-tools.ts
@@ -49,6 +49,7 @@ import {
} from "../core/search/retrieval-trail.ts";
import { probeRetrievalCorpus } from "../core/search/pipeline/outcome.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";
+import { contextReach } from "./tool-contract.ts";
import type { ServerContext, ToolDefinition } from "./tool-contract.ts";
import {
AGENT_SCOPE_SCHEMA,
@@ -940,6 +941,10 @@ async function toolBrainSearch(
...(properties !== undefined ? { properties } : {}),
...(degreeFilters !== undefined ? { degreeFilters } : {}),
...(visibility !== undefined ? { visibility } : {}),
+ // The reach the transport minted for this caller. Carried into the
+ // cross-vault union too, which spreads these options onto every
+ // federated leg, so a federated caller is bound by the same rule.
+ transportReach: contextReach(ctx),
...(agentScope !== undefined ? { agentScope } : {}),
...(scope !== undefined ? { scope } : {}),
...(structuredQuery !== undefined ? { structuredQuery } : {}),
@@ -1298,7 +1303,12 @@ async function toolBrainRecallFeedback(
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
- const outcome = await captureRecallFeedback(config, { query, resultPath, verdict });
+ const outcome = await captureRecallFeedback(config, {
+ query,
+ resultPath,
+ verdict,
+ transportReach: contextReach(ctx),
+ });
return {
recorded: true,
result_found: outcome.resultFound,
@@ -1455,7 +1465,14 @@ async function toolBrainEval(
let report;
try {
report = await withTimeout(
- runRecallBenchmark(config, dataset, { ...(k !== undefined ? { k } : {}), expand }),
+ runRecallBenchmark(config, dataset, {
+ ...(k !== undefined ? { k } : {}),
+ expand,
+ // The dataset is the caller's, and so is the reach it is scored
+ // at: `hit` / `rank` / `answerContained` over a corpus the caller
+ // did not earn is an oracle, not a metric.
+ transportReach: contextReach(ctx),
+ }),
EVAL_TIMEOUT_MS,
searchTimeoutError,
);
@@ -1560,6 +1577,7 @@ async function toolBrainFileContext(
const agentScope = coerceAgentScope(ctx, args, false);
const outcome = await fileContextRecall(config, {
...(agentScope !== undefined ? { agentScope } : {}),
+ transportReach: contextReach(ctx),
filePath,
...(limit !== undefined ? { limit } : {}),
...(minBytes !== undefined ? { minBytes } : {}),
@@ -1690,6 +1708,7 @@ async function toolBrainSearchExpand(
result = await withTimeout(
expandHit(config, {
chunkId: rawChunk,
+ transportReach: contextReach(ctx),
...(expandScope !== undefined ? { agentScope: expandScope } : {}),
...(rawLimit !== undefined ? { rawLimit } : {}),
...(cursor !== undefined ? { cursor } : {}),
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index bf62f542..64b57865 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -11,6 +11,7 @@ import {
} from "../core/config.ts";
import { emitMcpRouteLatency, type McpRouteStatus } from "../core/brain/mcp-route-metrics.ts";
import { assertKnownArguments } from "./argument-guard.ts";
+import { assertNoCallerSuppliedReach } from "./reach-refusal.ts";
import { buildInstructions } from "./instructions.ts";
import {
INTERNAL_ERROR,
@@ -45,6 +46,7 @@ import { ArtifactStore } from "./artifact-store.ts";
import { applyPreviewBudget } from "./preview-budget.ts";
import { evaluateToolCapabilities, type RuntimeCapabilityWindow } from "./capabilities.ts";
import type { InstallTargetId } from "../core/runtime/host-facts.ts";
+import { resolvedTransportReach, type TransportReach } from "../core/graph/transport-reach.ts";
/** TTL after which a prior process's artifact run directory is pruned. */
const ARTIFACT_TTL_MS = 24 * 60 * 60 * 1000;
@@ -87,6 +89,17 @@ export interface MCPServerRuntimeOptions {
* write inside their own loops.
*/
readonly sendNotification?: (notification: JsonRpcNotification) => void;
+ /**
+ * The reach this transport establishes for every caller it accepts
+ * (`src/core/graph/transport-reach.ts`).
+ *
+ * Absent means no transport minted one - an embedded caller, a probe,
+ * a test - and that resolves to {@link TRANSPORT_REACH.remote}, the
+ * narrowest. A transport that owns the fact sets it AFTER spreading a
+ * caller's options, exactly as `sendNotification` is set, so a runtime
+ * option cannot override what the transport established.
+ */
+ readonly reach?: TransportReach;
}
export interface JsonRpcRequest {
@@ -121,6 +134,8 @@ export class MCPServer {
private readonly routeMetricsEnabled: boolean;
/** See {@link MCPServerRuntimeOptions.sendNotification}. */
private readonly sendNotification: ((notification: JsonRpcNotification) => void) | undefined;
+ /** See {@link MCPServerRuntimeOptions.reach}; fail-closed when unminted. */
+ readonly reach: TransportReach;
constructor(opts: MCPServerOptions, runtimeOpts: MCPServerRuntimeOptions = {}) {
this.vault = opts.vault;
@@ -138,6 +153,7 @@ export class MCPServer {
this.capabilityReport = evaluated.report;
this.routeMetricsEnabled = routeMetricsGate(this.configPath ?? undefined);
this.sendNotification = runtimeOpts.sendNotification;
+ this.reach = resolvedTransportReach(runtimeOpts.reach);
const runId = runtimeOpts.artifactRunId ?? `run-${process.pid}-${Date.now().toString(36)}`;
this.artifactStore = new ArtifactStore({ vault: this.vault, runId });
// Best-effort housekeeping: clear prior processes' stale artifacts.
@@ -157,6 +173,7 @@ export class MCPServer {
repoRoot: this.repoRoot,
capabilityReport: this.capabilityReport,
artifactStore: this.artifactStore,
+ reach: this.reach,
// Owner-scope isolation (context-integrity-gates, Unit A): the
// only source of identity for `brain_context`, which takes no
// arguments. Resolved per access, like `resolveAgentName`'s other
@@ -210,6 +227,11 @@ export class MCPServer {
args: Record<string, unknown>,
onProgress?: ProgressSink,
): Promise<unknown> {
+ // Before the unknown-argument gate: a caller naming the visibility
+ // boundary is told about the boundary, not offered a typo suggestion
+ // for it - and the rule holds for an open schema, which that gate
+ // cannot see.
+ assertNoCallerSuppliedReach(tool, args);
assertKnownArguments(tool, args);
if (!this.routeMetricsEnabled) return tool.handler(this.context, args, onProgress);
const start = performance.now();
@@ -354,7 +376,10 @@ export class MCPServer {
if (typeof uri !== "string") {
throw new MCPError(INVALID_PARAMS, "resources/read requires a string `uri`");
}
- const content = readResource({ vault: this.vault, agentName: this.context.agentName }, uri);
+ const content = readResource(
+ { vault: this.vault, agentName: this.context.agentName, reach: this.reach },
+ uri,
+ );
return { contents: [content] };
}
diff --git a/src/mcp/stdio.ts b/src/mcp/stdio.ts
index 16314cc2..045d0a0e 100644
--- a/src/mcp/stdio.ts
+++ b/src/mcp/stdio.ts
@@ -23,6 +23,21 @@ import { errorResponse, type JsonRpcResponse } from "./server.ts";
import { INVALID_REQUEST, PARSE_ERROR, type JsonRpcNotification } from "./protocol.ts";
import { RequestDrain, resolveDrainDeadlineMs, type DrainOutcome } from "./drain.ts";
import { ORIGIN_CHANNEL, setOriginChannel } from "../core/origin-channel.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../core/graph/transport-reach.ts";
+
+/**
+ * What a stdio connection establishes about its caller.
+ *
+ * `local`, and the reason is the process tree rather than the protocol:
+ * this transport is spoken over the stdin and stdout of a process the
+ * caller started, so the caller already holds whatever filesystem access
+ * that process runs with. It does NOT prove operator intent - a remote
+ * host can spawn a stdio subprocess - and the alternative, minting
+ * `remote` here, would take an operator's own reserved pages away from
+ * their own editor and their own CLI. The limit is stated rather than
+ * papered over; see `src/core/graph/transport-reach.ts`.
+ */
+export const STDIO_TRANSPORT_REACH: TransportReach = TRANSPORT_REACH.local;
/**
* Any frame this transport writes: a response to a request, or a
@@ -40,6 +55,8 @@ type OutboundFrame = JsonRpcResponse | JsonRpcNotification;
*/
export interface StdioTransportHandle {
readonly drain: RequestDrain;
+ /** The reach this transport minted for every request it will carry. */
+ readonly reach: TransportReach;
/** Stop reading new lines, await the in-flight request, end the loop. */
close(): Promise<DrainOutcome>;
}
@@ -85,6 +102,10 @@ export async function serveStdio(
const server = new MCPServer(ctx, {
...runtimeOpts,
sendNotification: (notification) => writeFrame(stdout, notification),
+ // A transport fact, so it is set after the caller's options for the
+ // same reason `sendNotification` is: a runtime option must not be
+ // able to claim a reach this transport did not establish.
+ reach: STDIO_TRANSPORT_REACH,
});
const rl = createInterface({ input: stdin, crlfDelay: Infinity });
@@ -92,6 +113,7 @@ export async function serveStdio(
const deadlineMs = ioOpts.drainDeadlineMs ?? resolveDrainDeadlineMs(process.env);
ioOpts.onStart?.({
drain,
+ reach: STDIO_TRANSPORT_REACH,
close: async () => {
// The wait comes first and the reader is closed after it: closing
// the interface while a `tools/call` is still running would end the
@@ -203,6 +225,7 @@ export async function serveStdioFromString(
const server = new MCPServer(ctx, {
...opts,
sendNotification: (notification) => out.push(frameLine(notification)),
+ reach: STDIO_TRANSPORT_REACH,
});
for (const rawLine of input.split("\n")) {
const line = rawLine.trim();
diff --git a/src/mcp/tool-contract.ts b/src/mcp/tool-contract.ts
index c8922bf1..b22e7560 100644
--- a/src/mcp/tool-contract.ts
+++ b/src/mcp/tool-contract.ts
@@ -12,6 +12,7 @@
* single downward dependency direction.
*/
+import { resolvedTransportReach, type TransportReach } from "../core/graph/transport-reach.ts";
import type { OutputSchema } from "./output-contract.ts";
import type { ArtifactStore } from "./artifact-store.ts";
import type { ProgressSink } from "../core/brain/progress.ts";
@@ -109,6 +110,20 @@ export interface ServerContext {
* back through it. Optional so manually-built contexts stay valid.
*/
readonly artifactStore?: ArtifactStore;
+ /**
+ * How far the caller of this process had to reach to get here, minted
+ * by the transport that accepted the request (see
+ * `src/core/graph/transport-reach.ts`).
+ *
+ * Optional on the TYPE and mandatory in EFFECT: read it through
+ * {@link contextReach}, never directly. A context assembled by hand -
+ * an embedded caller, a test - established nothing about who is asking,
+ * and {@link contextReach} answers that with the narrowest reach rather
+ * than the widest. The field is optional so those contexts stay valid;
+ * the reader is what makes the omission fail closed instead of silently
+ * granting local access.
+ */
+ readonly reach?: TransportReach;
/**
* Resolved agent identity for this server process
* (context-integrity-gates, Unit A), from `resolveAgentName`.
@@ -170,3 +185,16 @@ export interface ToolDefinition {
onProgress?: ProgressSink,
) => Promise<unknown> | unknown;
}
+
+/**
+ * The reach a handler must answer at, resolved fail-closed.
+ *
+ * A context carrying no minted reach is not a context that proved local
+ * access; it is one where nobody established anything, and an
+ * unestablished trust level is not the absence of a boundary. Same
+ * convention `entityStatusInScope` follows for a status outside its
+ * vocabulary, and `owner-scope-view.ts` for an unresolved owner.
+ */
+export function contextReach(ctx: ServerContext): TransportReach {
+ return resolvedTransportReach(ctx.reach);
+}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 47033255..b2936d3d 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -53,6 +53,7 @@ import { unresolvedField, vaultPathField } from "./vault-path-field.ts";
import {
TOOL_SCOPE,
TOOL_SCOPES,
+ contextReach,
type ServerContext,
type ToolCapabilityReport,
type ToolDefinition,
@@ -217,8 +218,14 @@ async function toolQuery(
const scope = normalizeAgentScope(coerceAgentScope(ctx, args, false));
const notices: DegradationNotice[] = [];
+ // Root B: the reach the transport minted for this caller. A page
+ // reserved against remote reads never reaches the ownership filter
+ // below, and never reaches the count either.
+ const reach = contextReach(ctx);
const listed =
- scope === null ? listVaultPages(ctx.vault) : listVaultPages(ctx.vault, { notices });
+ scope === null
+ ? listVaultPages(ctx.vault, { reach })
+ : listVaultPages(ctx.vault, { notices, reach });
const unreadable = new Set(
notices
.filter((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable)
diff --git a/src/openclaw/index.ts b/src/openclaw/index.ts
index 90ccf927..4df6282c 100644
--- a/src/openclaw/index.ts
+++ b/src/openclaw/index.ts
@@ -17,11 +17,26 @@ import { probeVaultDirectory } from "../core/vault-presence.ts";
import { doctor } from "../core/doctor.ts";
import { buildReminder } from "../core/identity-reminder.ts";
import { listVaultPages } from "../core/vault.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../core/graph/transport-reach.ts";
import { ENTITY_STATUS_SCOPE, vaultPageInStatusScope } from "../core/brain/entities/page-scope.ts";
import { deriveRuntimeAgentName, normalizeAgentArgument } from "../core/agent-identity.ts";
import { vaultRelative as vaultRelativePath } from "../core/path-safety.ts";
import { vaultPathField } from "../mcp/vault-path-field.ts";
+/**
+ * What this runtime establishes about the caller of its tools.
+ *
+ * `remote`, and the distinction from the CLI is the caller rather than
+ * the machine. A CLI verb is typed by the operator; these tools are
+ * called by a model, over a conversation whose steering this plugin
+ * cannot see. Running on the operator's own host proves that the PROCESS
+ * has filesystem access, not that the party asking is entitled to a page
+ * the operator reserved - so this surface takes the narrowest reach, and
+ * an operator who wants those pages in this runtime reads them the way
+ * they reserved them: locally.
+ */
+const OPENCLAW_TRANSPORT_REACH: TransportReach = TRANSPORT_REACH.remote;
+
interface PluginConfig {
vault?: string;
agentName?: string;
@@ -125,7 +140,7 @@ export default definePluginEntry({
// by title, which is exactly the surface that would hand one back, and
// it is a page walker rather than an entity reader so the entity read
// census does not cover it. Non-entity pages are unaffected.
- const pages = listVaultPages(vault).filter((p) =>
+ const pages = listVaultPages(vault, { reach: OPENCLAW_TRANSPORT_REACH }).filter((p) =>
vaultPageInStatusScope(p.metadata, ENTITY_STATUS_SCOPE.readable),
);
const needle = pattern ? pattern.toLowerCase() : null;
diff --git a/tests/cli/search-check-visibility-honesty.test.ts b/tests/cli/search-check-visibility-honesty.test.ts
index a3050581..766ad6b7 100644
--- a/tests/cli/search-check-visibility-honesty.test.ts
+++ b/tests/cli/search-check-visibility-honesty.test.ts
@@ -2,22 +2,26 @@
* `o2b search check`'s visibility honesty finding
* (nothing-writes-silently, unit H, form B).
*
- * The defect: `visibility: private` frontmatter reads as a privacy
- * boundary and is a caller-supplied view filter honoured by exactly one
- * lane (`search()`'s pool-filters pipeline). This finding names the gap,
- * with a count derived from `visibility-surface-registry.ts`'s own
- * exported list - never a hand-written number - and only when the
- * vault/index actually carries at least one tagged page.
+ * The finding was written when `visibility:` was a caller-supplied view
+ * filter honoured by exactly one lane, and it said so. The reserved token
+ * is now enforced at three read roots, so the line reports what is still
+ * true instead: how many documents reserve themselves, how many
+ * enumerated surfaces still do not consult the field, and how many
+ * documents the index cannot measure. Every number is derived - the
+ * surface counts from `visibility-surface-registry.ts`'s own exported
+ * list, the document counts from the index's own column - and none is
+ * hand-written.
*
* The claims pinned here:
*
* 1. A vault that never uses `visibility:` renders neither the JSON key
* nor the human line - both shapes stay silent on it.
* 2. A vault with a tagged page renders `visibility_honesty` in JSON
- * with `excluded_surface_count` / `total_surface_count`, and the
- * human line under the same label, beside `pending_vectors:` and
- * `embedder_record:`.
- * 3. The finding never changes the exit code - it is an honesty
+ * with all four counts, and the human line under the same label,
+ * beside `pending_vectors:` and `embedder_record:`.
+ * 3. The unmeasured population is reported rather than absorbed into
+ * the measured one.
+ * 4. The finding never changes the exit code - it is an honesty
* statement, not a fault.
*/
@@ -62,15 +66,22 @@ test("a vault with one visibility-tagged page renders the finding in both shapes
expect(finding).toBeDefined();
expect(finding["excluded_surface_count"]).toBe(excludedCallableVisibilitySurfaces().length);
expect(finding["total_surface_count"]).toBe(callableVisibilitySurfaces().length);
+ // One tagged page in the fixture, and it is the reserved token.
+ expect(finding["reserved_document_count"]).toBe(1);
+ // Every document in this fixture has a frontmatter chunk to measure.
+ expect(finding["unmeasured_document_count"]).toBe(0);
const human = await runCli(["search", "check", "--vault", vault, "--db", dbPath]);
expect(human.returncode).toBe(0);
expect(human.stdout).toContain("visibility_honesty:");
- expect(human.stdout).toContain("caller-supplied view filter, not a privacy boundary");
+ expect(human.stdout).toContain("reserve themselves against remote reads");
expect(human.stdout).toContain(`${excludedCallableVisibilitySurfaces().length} of the `);
// The line names its own scope: the census's population, not the
// product's whole surface area.
expect(human.stdout).toContain("the visibility census enumerates");
+ // And it names the population it could not measure rather than
+ // folding it into "declares nothing".
+ expect(human.stdout).toContain("hold no frontmatter the index can measure");
} finally {
cleanup();
}
diff --git a/tests/core/architecture/verdict-vocabulary-census.test.ts b/tests/core/architecture/verdict-vocabulary-census.test.ts
index d8a6b95d..2977cc87 100644
--- a/tests/core/architecture/verdict-vocabulary-census.test.ts
+++ b/tests/core/architecture/verdict-vocabulary-census.test.ts
@@ -402,6 +402,11 @@ import {
ORIGIN_CHANNELS,
} from "../../../src/core/origin-channel.ts";
import { lexCode } from "../../helpers/source-lexer.ts";
+import {
+ TRANSPORT_REACH,
+ TRANSPORT_REACHES,
+ isTransportReach,
+} from "../../../src/core/graph/transport-reach.ts";
interface VocabularyUnderCensus {
/** Identifies the vocabulary in a failure message. */
@@ -1094,6 +1099,16 @@ const CENSUS: ReadonlyArray<VocabularyUnderCensus> = Object.freeze([
members: OWNER_SCOPE_REFUSALS,
guard: isOwnerScopeRefusal,
},
+ {
+ // private-is-not-a-suggestion, U2. How far the caller of this process
+ // had to reach to get here. Minted by the transport and never parsed
+ // out of a request, so the guard is for a value read back off a
+ // stored envelope rather than for one arriving from a caller.
+ name: "TRANSPORT_REACH",
+ values: TRANSPORT_REACH,
+ members: TRANSPORT_REACHES,
+ guard: isTransportReach,
+ },
{
// U5. Whether a registered search origin could be read at all.
// `unreachable` and `unknown` are distinct members because "it is not
@@ -1502,7 +1517,7 @@ const SCANNED = scanVocabularies(SOURCE_TREE);
* How many four-piece vocabularies `src/` currently holds. Measured, and
* kept as an equality rather than a floor - see the population test.
*/
-const VOCABULARY_POPULATION = 73;
+const VOCABULARY_POPULATION = 74;
const REGISTERED = new Map(CENSUS.map((entry) => [entry.name, entry] as const));
describe("verdict vocabulary census", () => {
diff --git a/tests/core/architecture/visibility-surface-census.test.ts b/tests/core/architecture/visibility-surface-census.test.ts
index 6aeb900f..8a45ae06 100644
--- a/tests/core/architecture/visibility-surface-census.test.ts
+++ b/tests/core/architecture/visibility-surface-census.test.ts
@@ -81,11 +81,23 @@
* two modules away (the population rule reads the MCP file's own
* imports, not its whole call graph - deep-synthesis.ts is in
* population via `deepSynthesis`, not because knowledge-tools.ts itself
- * imports `search`); and `src/openclaw/` (the OpenClaw native plugin
- * adapter), which the charter scoped this sweep away from even though
- * `src/openclaw/index.ts` hosts its own `listVaultPages`-backed page
- * search with no visibility check - named here, not swept, and worth a
- * follow-up census of its own.
+ * imports `search`).
+ *
+ * `src/openclaw/` used to be named here as a stated blind spot - scoped
+ * away by the charter even though `src/openclaw/index.ts` hosts its own
+ * `listVaultPages`-backed page search with no visibility check. It is
+ * neither any more: the tree is swept (see {@link MCP_SOURCE_TREE}) and
+ * that walk takes a reach. The paragraph is rewritten rather than left
+ * standing, because a blind spot that has been closed mis-sizes the
+ * remaining work in the opposite direction from a blind spot that has
+ * been missed, and this list is the enforceable statement of coverage.
+ *
+ * The vocabulary itself is the live blind spot, and it has cost real
+ * surfaces: `runHygieneScan` and `planSkillPageDrafts` joined it only
+ * after a review found `brain_hygiene` and `brain_skill_proposals`
+ * disclosing reserved page paths from outside a population that could not
+ * see them. A producer reached through a `src/core/` helper is invisible
+ * here until someone names the helper.
*
* CLI population is NOT mechanically discovered the way the MCP one is:
* it is hand-enumerated, one row per MCP tool above that has a CLI
@@ -104,14 +116,19 @@ import { buildToolTable } from "../../../src/mcp/tools.ts";
import { listResources, listResourceTemplates } from "../../../src/mcp/resources.ts";
import { nestedCommand } from "../../../src/cli/command-manifest.ts";
import {
+ DIRECT_VAULT_READ_CATEGORY,
+ DIRECT_VAULT_READ_REGISTRY,
VISIBILITY_SURFACE_CATEGORY,
VISIBILITY_SURFACE_KIND,
VISIBILITY_SURFACE_REGISTRY,
+ type DirectVaultReadEntry,
type VisibilitySurfaceEntry,
} from "../../../src/core/search/visibility-surface-registry.ts";
const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
const MCP_ROOT = join(REPO_ROOT, "src", "mcp");
+const OPENCLAW_ROOT = join(REPO_ROOT, "src", "openclaw");
+const CLI_ROOT = join(REPO_ROOT, "src", "cli");
const SRC_ROOT = join(REPO_ROOT, "src");
// ─────────────────────────────────────────────────────────────────────────────
@@ -179,6 +196,15 @@ const NOTE_CONTENT_PRODUCERS: ReadonlyArray<ProducerRule> = Object.freeze([
"listVaultPages",
],
},
+ // Two producers that reach page content through a `src/core/` helper
+ // rather than through a vault or search primitive directly. They were
+ // the census's stated blind spot and cost it two live surfaces: the
+ // hygiene scan's freshness detector and the skill-page planner both
+ // walk with `MAINTENANCE_LANE_REACH` and both hand paths and titles to
+ // an MCP caller, so neither was counted in the denominator the
+ // operator-facing honesty line reports.
+ { specifierIncludes: "/hygiene/scan.ts", identifiers: ["runHygieneScan"] },
+ { specifierIncludes: "/skill-page-drafts.ts", identifiers: ["planSkillPageDrafts"] },
{ specifierIncludes: "/search/search.ts", identifiers: ["search"] },
{ specifierIncludes: "/search/index.ts", identifiers: ["search", "expandHit"] },
{ specifierIncludes: "/search/cards.ts", identifiers: ["expandHit"] },
@@ -372,7 +398,17 @@ function discoverMcpToolPopulation(
return found;
}
-const MCP_SOURCE_TREE = readTree(MCP_ROOT);
+/**
+ * The tool-surface tree. `src/openclaw/` joined `src/mcp/` here when the
+ * boundary reached it: the previous census named the OpenClaw page walker
+ * as an un-swept surface and left it out, which meant the one place the
+ * charter had already identified as a gap was the one place the sweep
+ * could not have found it. It registers its tools on the OpenClaw plugin
+ * api rather than in `buildToolTable`, but the names it registers are the
+ * same names the MCP surface publishes, so the real-tool filter admits
+ * them and the registry rows they land on are shared.
+ */
+const MCP_SOURCE_TREE = [...readTree(MCP_ROOT), ...readTree(OPENCLAW_ROOT)];
const REAL_TOOL_NAMES: ReadonlySet<string> = new Set(buildToolTable("full").map((t) => t.name));
const MCP_TOOL_POPULATION = discoverMcpToolPopulation(MCP_SOURCE_TREE, REAL_TOOL_NAMES);
@@ -404,8 +440,16 @@ function reasonProblems(entries: ReadonlyArray<VisibilitySurfaceEntry>): {
// Population pins - equalities, the way write-site-census pins its own counts
// ─────────────────────────────────────────────────────────────────────────────
-/** Measured: MCP tools whose file imports a note-content primitive. */
-const MCP_TOOL_POPULATION_SIZE = 43;
+/**
+ * Measured: MCP tools whose file imports a note-content primitive.
+ *
+ * 43 before the vocabulary gained `runHygieneScan` and
+ * `planSkillPageDrafts`. The five new names are `brain_hygiene` and
+ * `brain_skill_proposals`, which the sweep could not see and which were
+ * both leaking, plus the three tools that share `procedure-tools.ts` with
+ * the second of them and come in on the file-level rule.
+ */
+const MCP_TOOL_POPULATION_SIZE = 48;
/** Measured: MCP resources + templates, all excluded. */
const MCP_RESOURCE_POPULATION_SIZE = 8;
/** Measured: hand-enumerated CLI verb mirrors. */
@@ -454,12 +498,29 @@ describe("visibility surface census", () => {
expect(MCP_TOOL_POPULATION.size).toBe(MCP_TOOL_POPULATION_SIZE);
});
- test("brain_search and brain_file_context are the only two covered MCP tools", () => {
+ test("the covered MCP tools are exactly the ones a read root reaches", () => {
+ // Written out rather than derived: this list IS the measurement, and
+ // a tool joining or leaving it is a finding to name in the release
+ // rather than a number to re-take. Before this wave it was two.
const covered = REGISTRY_BY_KIND(VISIBILITY_SURFACE_KIND.mcpTool)
.filter((e) => e.category === VISIBILITY_SURFACE_CATEGORY.covered)
.map((e) => e.surface)
.toSorted();
- expect(covered).toEqual(["brain_file_context", "brain_search"]);
+ expect(covered).toEqual([
+ "brain_backlinks",
+ "brain_bridges",
+ "brain_clusters",
+ "brain_deep_synthesis",
+ "brain_eval",
+ "brain_file_context",
+ "brain_hygiene",
+ "brain_query",
+ "brain_recall_feedback",
+ "brain_search",
+ "brain_search_expand",
+ "brain_skill_proposals",
+ "second_brain_query",
+ ]);
});
});
@@ -476,11 +537,29 @@ describe("visibility surface census", () => {
expect(advertised.size).toBe(MCP_RESOURCE_POPULATION_SIZE);
});
- test("no MCP resource is covered - resources.ts never calls applyVisibilityScope", () => {
- const anyCovered = REGISTRY_BY_KIND(VISIBILITY_SURFACE_KIND.mcpResource).some(
- (e) => e.category === VISIBILITY_SURFACE_CATEGORY.covered,
- );
- expect(anyCovered).toBe(false);
+ test("the four templated readers are covered and the four whole-vault ones are not", () => {
+ // The split is the design, not an oversight: a templated reader is
+ // keyed by a caller-supplied id and is therefore root C, while the
+ // four whole-vault readers return Brain/active.md, the lessons
+ // digest and the status projection - shared artifacts by
+ // construction, which no page's reservation covers.
+ const byCategory = (category: string): string[] =>
+ REGISTRY_BY_KIND(VISIBILITY_SURFACE_KIND.mcpResource)
+ .filter((e) => e.category === category)
+ .map((e) => e.surface)
+ .toSorted();
+ expect(byCategory(VISIBILITY_SURFACE_CATEGORY.covered)).toEqual([
+ "osb://backlinks/{id}",
+ "osb://log/{date}",
+ "osb://preference/{id}",
+ "osb://topic/{slug}",
+ ]);
+ expect(byCategory(VISIBILITY_SURFACE_CATEGORY.excluded)).toEqual([
+ "osb://digest/latest",
+ "osb://lessons",
+ "osb://preferences/active",
+ "osb://status",
+ ]);
});
});
@@ -502,12 +581,24 @@ describe("visibility surface census", () => {
);
});
- test("no CLI verb is covered except the two search lanes", () => {
+ test("the covered CLI verbs are exactly the mirrors of the covered tools", () => {
+ // Each of these states its reach at the call site rather than
+ // inheriting a default. The verdict is admit-all, because the caller
+ // is the operator's own shell - which is a decision these verbs make
+ // rather than a question they skip.
const covered = REGISTRY_BY_KIND(VISIBILITY_SURFACE_KIND.cliVerb)
.filter((e) => e.category === VISIBILITY_SURFACE_CATEGORY.covered)
.map((e) => e.surface)
.toSorted();
- expect(covered).toEqual(["search query"]);
+ expect(covered).toEqual([
+ "brain backlinks",
+ "brain clusters",
+ "brain deep-synthesis",
+ "brain file-context",
+ "brain query",
+ "search expand",
+ "search query",
+ ]);
});
});
@@ -640,3 +731,145 @@ describe("the census can fail", () => {
expect([...population]).toEqual(["brain_synthetic_renamed"]);
});
});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Root closure: is there a fourth root?
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A direct filesystem READ. Writes are deliberately absent: this sweep is
+ * about what leaves the process, and `write-site-census.test.ts` is the
+ * one that watches what enters the vault.
+ */
+const FS_READ_RE = /\b(readFileSync|readdirSync|createReadStream|opendirSync)\s*\(/;
+
+/**
+ * A path built onto a vault root: `join(vault, …)`, `join(ctx.vault, …)`,
+ * `join(cfg.vault, …)`, `join(vaultDir, …)`. Read off the lexer's `code`
+ * view, so the word appearing inside a string literal or a comment cannot
+ * match.
+ */
+const VAULT_JOIN_RE = /\bjoin\(\s*[A-Za-z_.]*[Vv]ault[A-Za-z_.]*\s*,/;
+
+/** The trees a caller can reach this process through. */
+const SURFACE_TREES: ReadonlyArray<string> = Object.freeze([MCP_ROOT, CLI_ROOT, OPENCLAW_ROOT]);
+
+/**
+ * Every file in the surface trees that opens a vault path itself rather
+ * than going through one of the three read roots.
+ *
+ * Exported as a function of its input so the fixture below can run the
+ * same sweep over a synthetic intruder.
+ */
+function directVaultReadFiles(files: ReadonlyArray<CensusFile>): ReadonlySet<string> {
+ const found = new Set<string>();
+ for (const file of files) {
+ const code = lexedViews(file).code;
+ if (FS_READ_RE.test(code) && VAULT_JOIN_RE.test(code)) found.add(file.path);
+ }
+ return found;
+}
+
+const SURFACE_SOURCE_TREE = SURFACE_TREES.flatMap((root) => readTree(root));
+const DIRECT_VAULT_READERS = directVaultReadFiles(SURFACE_SOURCE_TREE);
+
+/** Measured: files in the surface trees that read a vault path directly. */
+const DIRECT_VAULT_READ_POPULATION_SIZE = 4;
+
+/**
+ * ## What this sweep cannot see, stated rather than implied
+ *
+ * It reads two SHAPES in one file's own text, so it is blind in the same
+ * four ways the tool sweep above is, plus two of its own:
+ *
+ * - a vault path built without `join` - a template literal, a
+ * `resolve()`, a path threaded in as an already-absolute string from
+ * a caller two modules away - reads as no vault path at all;
+ * - a read performed by a helper in `src/core/` that a surface file
+ * calls. That is not a gap in the guarantee so much as a restatement
+ * of it: `src/core/` is where the three roots live, and a core helper
+ * that reads a vault page without asking them is what the roots exist
+ * to be. It is out of THIS sweep's population and named here so a
+ * reader does not read root closure as more than it is.
+ *
+ * What it does establish is the claim the boundary actually rests on: no
+ * file a caller reaches this process through opens a vault page behind
+ * the roots' back without a written reason.
+ */
+describe("root closure", () => {
+ test("every direct vault reader is registered, and every row names one", () => {
+ const registered = new Set(DIRECT_VAULT_READ_REGISTRY.map((e) => e.file));
+ const unregistered = [...DIRECT_VAULT_READERS].filter((f) => !registered.has(f));
+ const stale = [...registered].filter((f) => !DIRECT_VAULT_READERS.has(f));
+ expect(unregistered.toSorted()).toEqual([]);
+ expect(stale.toSorted()).toEqual([]);
+ });
+
+ test("the population is measured, as an equality", () => {
+ expect(DIRECT_VAULT_READERS.size).toBe(DIRECT_VAULT_READ_POPULATION_SIZE);
+ });
+
+ test("every row carries a closed category and a reason of meaningful length", () => {
+ const values = new Set<string>(Object.values(DIRECT_VAULT_READ_CATEGORY));
+ const badCategory = DIRECT_VAULT_READ_REGISTRY.filter((e) => !values.has(e.category));
+ expect(badCategory).toEqual([]);
+ const { thin, lazy } = directReadReasonProblems(DIRECT_VAULT_READ_REGISTRY);
+ expect(thin.toSorted().join("\n")).toBe("");
+ expect(lazy.toSorted().join("\n")).toBe("");
+ });
+
+ test("the guarded reader actually consults the rule at the site of the read", () => {
+ // A category is a claim; this is the check that the claim is true of
+ // the file it is made about. A row that said `guarded` about a file
+ // that never asks would be exactly the decorative classification this
+ // census exists to prevent.
+ for (const entry of DIRECT_VAULT_READ_REGISTRY) {
+ if (entry.category !== DIRECT_VAULT_READ_CATEGORY.guarded) continue;
+ const file = SURFACE_SOURCE_TREE.find((f) => f.path === entry.file);
+ expect(file, `${entry.file} is registered but not in the swept tree`).toBeDefined();
+ expect(lexedViews(file!).code, entry.file).toContain("reachView");
+ }
+ });
+
+ test("a synthetic file reading a vault path directly is reported", () => {
+ const intruder: CensusFile = {
+ path: "src/mcp/brain/synthetic-reader.ts",
+ text:
+ 'import { readFileSync } from "node:fs";\n' +
+ 'import { join } from "node:path";\n' +
+ "export function leak(vault: string): string {\n" +
+ ' return readFileSync(join(vault, "notes", "secret.md"), "utf8");\n' +
+ "}\n",
+ };
+ expect([...directVaultReadFiles([intruder])]).toEqual([intruder.path]);
+ expect(DIRECT_VAULT_READ_REGISTRY.some((e) => e.file === intruder.path)).toBe(false);
+ });
+
+ test("a file that only WRITES a vault path is not swept in", () => {
+ // The sweep is about what leaves the process. A writer is
+ // `write-site-census.test.ts`'s population, not this one.
+ const writer: CensusFile = {
+ path: "src/cli/synthetic-writer.ts",
+ text:
+ 'import { writeFileSync } from "node:fs";\n' +
+ 'import { join } from "node:path";\n' +
+ "export function put(vault: string, body: string): void {\n" +
+ ' writeFileSync(join(vault, "notes", "new.md"), body);\n' +
+ "}\n",
+ };
+ expect([...directVaultReadFiles([writer])]).toEqual([]);
+ });
+});
+
+function directReadReasonProblems(entries: ReadonlyArray<DirectVaultReadEntry>): {
+ thin: string[];
+ lazy: string[];
+} {
+ const thin: string[] = [];
+ const lazy: string[] = [];
+ for (const e of entries) {
+ if (e.reason.trim().length < MIN_REASON_LENGTH) thin.push(`${e.file} (${e.reason.length})`);
+ if (LAZY_REASON_RE.test(e.reason)) lazy.push(e.file);
+ }
+ return { thin, lazy };
+}
diff --git a/tests/core/brain/artifact-ref-view.test.ts b/tests/core/brain/artifact-ref-view.test.ts
new file mode 100644
index 00000000..52e4e754
--- /dev/null
+++ b/tests/core/brain/artifact-ref-view.test.ts
@@ -0,0 +1,101 @@
+/**
+ * The reference grammar both rules ask through
+ * (`src/core/brain/artifact-ref-view.ts`).
+ *
+ * `visible()` reads a reference that resolves to no artifact on disk as
+ * "this row names nothing that could be hidden" and lets the row
+ * through. That reading is only true for the spellings the resolver
+ * would have FOUND had the artifact existed - so every spelling it
+ * cannot resolve is a fail-open, on a rule whose whole posture is
+ * fail-closed. These are the spellings.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { artifactRefView } from "../../../src/core/brain/artifact-ref-view.ts";
+import { logEntryArtifactRefs } from "../../../src/core/brain/log.ts";
+import type { BrainLogEntry } from "../../../src/core/brain/log.ts";
+
+const HIDDEN_ID = "pref-hidden";
+const HIDDEN_REL = `Brain/preferences/${HIDDEN_ID}.md`;
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-artifact-ref-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+ writeFileSync(join(vault, HIDDEN_REL), "---\ntopic: hidden\n---\n\nthe rule\n");
+});
+
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+/** A view that hides exactly the one page above, and nothing else. */
+const hidingView = () => artifactRefView(vault, (rel) => rel !== HIDDEN_REL);
+
+describe("reference spellings the rule must resolve", () => {
+ const SPELLINGS: ReadonlyArray<{ readonly ref: string; readonly why: string }> = [
+ { ref: HIDDEN_ID, why: "the bare id" },
+ { ref: `[[${HIDDEN_ID}]]`, why: "the wikilink form" },
+ { ref: HIDDEN_REL, why: "the vault-relative path" },
+ { ref: `[[${HIDDEN_REL}]]`, why: "the path as a wikilink" },
+ { ref: `[[${HIDDEN_ID}|the rule]]`, why: "an ALIASED wikilink" },
+ { ref: `[[${HIDDEN_ID}#Raw]]`, why: "an ANCHORED wikilink" },
+ { ref: `[[${HIDDEN_REL}|the rule]]`, why: "an aliased PATH wikilink" },
+ { ref: `${HIDDEN_ID}|the rule`, why: "decoration with no brackets left on it" },
+ ];
+
+ for (const { ref, why } of SPELLINGS) {
+ test(`${why} resolves to the hidden page and is withheld`, () => {
+ expect(hidingView().visible(ref), why).toBe(false);
+ });
+ }
+
+ test("a reference that genuinely names nothing still passes", () => {
+ const view = hidingView();
+ expect(view.visible("pref-never-existed")).toBe(true);
+ expect(view.visible("[[pref-never-existed|alias]]")).toBe(true);
+ expect(view.visible(null)).toBe(true);
+ expect(view.visible(undefined)).toBe(true);
+ expect(view.visible("")).toBe(true);
+ });
+
+ test("a row survives only when every reference it names survives", () => {
+ const view = hidingView();
+ expect(view.row("pref-other", HIDDEN_ID)).toBe(false);
+ expect(view.row("pref-other", "pref-another")).toBe(true);
+ });
+});
+
+describe("what a log entry offers the rule", () => {
+ const entry = (body: Record<string, unknown>): BrainLogEntry =>
+ ({
+ timestamp: "2026-05-04T00:00:00Z",
+ eventType: "apply-evidence",
+ body,
+ }) as unknown as BrainLogEntry;
+
+ test("a key outside the old four-name list is still offered", () => {
+ // `target`, `subject_a`, `successor`, `source_path` and the rest are
+ // real writer keys in this tree; the enumeration that omitted them
+ // made their rows unconditionally visible.
+ for (const key of ["target", "subject_a", "successor", "predecessor", "source_path", "note"]) {
+ expect(hidingView().keep([entry({ [key]: HIDDEN_ID })], logEntryArtifactRefs)).toEqual([]);
+ }
+ });
+
+ test("an ARRAY-valued payload is flattened rather than dropped", () => {
+ // `parseLogDay` produces an array whenever a key repeats or uses the
+ // indented sub-bullet form, and a `typeof === "string"` test answered
+ // `undefined` for exactly those.
+ const rows = [entry({ path: ["notes/open.md", HIDDEN_ID] })];
+ expect(hidingView().keep(rows, logEntryArtifactRefs)).toEqual([]);
+ });
+
+ test("a row naming nothing hidden is kept, so the widening is not blanket-denying", () => {
+ const rows = [entry({ path: "notes/open.md", detail: "some prose about a rule" })];
+ expect(hidingView().keep(rows, logEntryArtifactRefs)).toEqual(rows);
+ });
+});
diff --git a/tests/core/brain/deep-synthesis.test.ts b/tests/core/brain/deep-synthesis.test.ts
index 3e5719c7..e9fd797c 100644
--- a/tests/core/brain/deep-synthesis.test.ts
+++ b/tests/core/brain/deep-synthesis.test.ts
@@ -17,6 +17,7 @@ import {
} from "../../../src/core/brain/deep-synthesis.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
let vault: string;
let dbPath: string;
@@ -173,7 +174,16 @@ test("a matched note with no retrievable content is excluded with a reason, neve
// Delete after indexing: the index still surfaces it, but its bytes are gone.
rmSync(join(vault, "Brain/notes/ghost.md"));
- const report = await deepSynthesis(makeConfig({ vault, dbPath }), "manticores", { now: NOW });
+ // The subject here is how an unretrievable note is REPORTED, not who may
+ // see it: an unreadable page has an unmeasurable visibility claim and is
+ // withheld at remote reach (pinned in
+ // `tests/core/search/visibility-filter.test.ts`). This case asks at the
+ // reach that still surfaces it - the operator's own, who is the caller
+ // who has to act on the exclusion reason.
+ const report = await deepSynthesis(makeConfig({ vault, dbPath }), "manticores", {
+ now: NOW,
+ transportReach: TRANSPORT_REACH.local,
+ });
// Still a matched note (existing field, unchanged).
expect(report.notes.some((n) => n.path === "Brain/notes/ghost.md")).toBe(true);
// But never a finding - it has no evidence identity.
diff --git a/tests/core/brain/dream-progress.test.ts b/tests/core/brain/dream-progress.test.ts
index bb458b58..436d54df 100644
--- a/tests/core/brain/dream-progress.test.ts
+++ b/tests/core/brain/dream-progress.test.ts
@@ -15,7 +15,7 @@
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import { cpSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -142,10 +142,32 @@ describe("dream progress", () => {
// forensic evidence of when the pass really ran.
// Everything else the pass authored is compared.
const EXCLUDED_PREFIXES = ["Brain/.snapshots/", "Brain/log/dream-runs/"];
+ // The archive's SIZE escapes that first exclusion: the snapshot log
+ // entry records `size_bytes`, so the tar's mtime nondeterminism is
+ // republished into a file this assertion does compare, and the two
+ // trees' mtimes differ whenever the copy straddles a second. The
+ // field is NORMALISED rather than the day log excluded - excluding
+ // it would drop the pass's main authored artifact from the
+ // comparison, which is most of what this test is for. Every other
+ // member of that entry (run_id, reason, channel) still compares.
+ const ARCHIVE_SIZE_FIELD = /(size_bytes"?:\s*"?)\d+/g;
+ const ARCHIVE_SIZE_PLACEHOLDER = "$1<archive-size>";
+ const NORMALISED_PREFIX = "Brain/log/";
const authored = (root: string): Map<string, string> => {
const kept = new Map<string, string>();
for (const [path, digest] of digestVaultFiles(root)) {
- if (!EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) kept.set(path, digest);
+ if (EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) continue;
+ // Digest everywhere else; the day log is text, so it is compared
+ // as normalised text and a mismatch prints the offending line.
+ kept.set(
+ path,
+ path.startsWith(NORMALISED_PREFIX)
+ ? readFileSync(join(root, path), "utf8").replaceAll(
+ ARCHIVE_SIZE_FIELD,
+ ARCHIVE_SIZE_PLACEHOLDER,
+ )
+ : digest,
+ );
}
return kept;
};
diff --git a/tests/core/graph/remote-readability.test.ts b/tests/core/graph/remote-readability.test.ts
new file mode 100644
index 00000000..c795db3f
--- /dev/null
+++ b/tests/core/graph/remote-readability.test.ts
@@ -0,0 +1,114 @@
+/**
+ * Deny-by-default remote readability (private-is-not-a-suggestion, unit 1).
+ *
+ * One reserved visibility token means "not readable by a caller that only
+ * reached this server over the network". The predicate that answers it is
+ * the single spelling of that rule; every other visibility token keeps
+ * exactly the caller-liftable scoping semantics `isVisible` already gives
+ * it.
+ *
+ * The reserved token is a controlled-vocabulary identifier, in the same
+ * sense as `kind: entity` or an entity `status` value - not a
+ * natural-language phrase, and not a closed list of them.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ REMOTE_DENY_VISIBILITY_TOKEN,
+ isRemotelyReadable,
+ isVisible,
+ normalizeVisibilityScope,
+ pageVisibility,
+} from "../../../src/core/graph/visibility.ts";
+import {
+ TRANSPORT_REACH,
+ TRANSPORT_REACHES,
+ isTransportReach,
+} from "../../../src/core/graph/transport-reach.ts";
+
+/** A token that is NOT the reserved one, for the "unaffected" arm. */
+const ORDINARY_TOKEN = "team";
+
+describe("the transport reach vocabulary", () => {
+ test("is closed, and its membership list matches the object", () => {
+ expect([...TRANSPORT_REACHES].toSorted()).toEqual(Object.values(TRANSPORT_REACH).toSorted());
+ });
+
+ test("narrows only its own members", () => {
+ for (const reach of TRANSPORT_REACHES) expect(isTransportReach(reach)).toBe(true);
+ for (const other of ["", "full", "reduced", "LOCAL", 0, null, undefined, {}]) {
+ expect(isTransportReach(other)).toBe(false);
+ }
+ });
+});
+
+describe("the reserved token", () => {
+ test("is already in the normal form page tags are read into", () => {
+ // A second spelling of the reserved token would be a second rule.
+ expect(pageVisibility({ visibility: REMOTE_DENY_VISIBILITY_TOKEN })).toEqual([
+ REMOTE_DENY_VISIBILITY_TOKEN,
+ ]);
+ });
+
+ test("is matched through the same NFC + lower-case normalisation", () => {
+ const upper = REMOTE_DENY_VISIBILITY_TOKEN.toUpperCase();
+ expect(
+ isRemotelyReadable(pageVisibility({ visibility: ` ${upper} ` }), TRANSPORT_REACH.remote),
+ ).toBe(false);
+ });
+});
+
+describe("isRemotelyReadable truth table", () => {
+ const cases: ReadonlyArray<{
+ readonly name: string;
+ readonly tags: ReadonlyArray<string>;
+ readonly local: boolean;
+ readonly remote: boolean;
+ }> = [
+ { name: "untagged", tags: [], local: true, remote: true },
+ {
+ name: "the reserved token alone",
+ tags: [REMOTE_DENY_VISIBILITY_TOKEN],
+ local: true,
+ remote: false,
+ },
+ { name: "a non-reserved token alone", tags: [ORDINARY_TOKEN], local: true, remote: true },
+ {
+ name: "the reserved token beside a non-reserved one",
+ tags: [ORDINARY_TOKEN, REMOTE_DENY_VISIBILITY_TOKEN],
+ local: true,
+ remote: false,
+ },
+ ];
+
+ for (const c of cases) {
+ test(`${c.name} is ${c.local ? "readable" : "withheld"} at local reach`, () => {
+ expect(isRemotelyReadable(c.tags, TRANSPORT_REACH.local)).toBe(c.local);
+ });
+ test(`${c.name} is ${c.remote ? "readable" : "withheld"} at remote reach`, () => {
+ expect(isRemotelyReadable(c.tags, TRANSPORT_REACH.remote)).toBe(c.remote);
+ });
+ }
+});
+
+describe("the predicate is independent of the caller's requested scope", () => {
+ /**
+ * The caller argument keeps narrowing and can no longer lift: a scope
+ * naming the reserved token satisfies `isVisible` and is still withheld
+ * at remote reach.
+ */
+ test("a requested scope naming the reserved token does not lift it", () => {
+ const tags = pageVisibility({ visibility: [REMOTE_DENY_VISIBILITY_TOKEN] });
+ const scope = normalizeVisibilityScope([REMOTE_DENY_VISIBILITY_TOKEN]);
+ expect(isVisible(tags, scope)).toBe(true);
+ expect(isRemotelyReadable(tags, TRANSPORT_REACH.remote)).toBe(false);
+ });
+
+ test("a non-reserved token still needs the caller to ask for it", () => {
+ const tags = pageVisibility({ visibility: [ORDINARY_TOKEN] });
+ expect(isRemotelyReadable(tags, TRANSPORT_REACH.remote)).toBe(true);
+ expect(isVisible(tags, normalizeVisibilityScope([]))).toBe(false);
+ expect(isVisible(tags, normalizeVisibilityScope([ORDINARY_TOKEN]))).toBe(true);
+ });
+});
diff --git a/tests/core/search/agent-scope-surfaces.test.ts b/tests/core/search/agent-scope-surfaces.test.ts
index 90636cd1..b315e249 100644
--- a/tests/core/search/agent-scope-surfaces.test.ts
+++ b/tests/core/search/agent-scope-surfaces.test.ts
@@ -22,6 +22,7 @@ import { expandHit } from "../../../src/core/search/cards.ts";
import { indexVault, resolveSearchConfig, search } from "../../../src/core/search/index.ts";
import { SearchError, type ResolvedSearchConfig } from "../../../src/core/search/types.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
const OWNER_A = "agent-a";
const OWNER_B = "agent-b";
@@ -187,9 +188,21 @@ test("an unreadable owner-tagged file is hidden from another owner", async () =>
test("an unscoped call still serves a deleted file's indexed chunk", async () => {
const chunkId = await chunkIdFor("notes/owned-a.md");
rmSync(join(vault, "notes", "owned-a.md"));
- const unscoped = await search(config, { query: QUERY, limit: 20 });
+ // Unscoped means no OWNERSHIP filtering. The reach is minted separately
+ // and is what decides whether an unmeasurable page may be answered at
+ // all, so this case states the local one - the operator's own CLI, who
+ // is exactly the caller who needs to see the stale row in order to fix
+ // it. The remote counterpart is pinned in
+ // `tests/core/search/visibility-filter.test.ts`.
+ const unscoped = await search(config, {
+ query: QUERY,
+ limit: 20,
+ transportReach: TRANSPORT_REACH.local,
+ });
expect(unscoped.results.map((r) => r.path)).toContain("notes/owned-a.md");
- expect((await expandHit(config, { chunkId })).note.path).toBe("notes/owned-a.md");
+ expect(
+ (await expandHit(config, { chunkId, transportReach: TRANSPORT_REACH.local })).note.path,
+ ).toBe("notes/owned-a.md");
});
// ----- A2: a present-but-unusable `owner:` is never ownerless --------------
diff --git a/tests/core/search/query-cache.test.ts b/tests/core/search/query-cache.test.ts
index a1e939bb..49905217 100644
--- a/tests/core/search/query-cache.test.ts
+++ b/tests/core/search/query-cache.test.ts
@@ -33,3 +33,28 @@ test("property-filter order does not change the key (canonical)", () => {
const b = buildCacheKey(opts({ properties: new Map([["k", ["2", "1"]]]) }), "p", "fp");
expect(a).toBe(b);
});
+
+// --- Transport reach partitions the cache (private-is-not-a-suggestion) -----
+//
+// The reach decides which pages are in the pool at all, so a `local`
+// outcome and a `remote` outcome must never collide on one row. The
+// cache lives in the shared `query_cache` table, which the operator's
+// CLI (local) and the HTTP MCP server (remote) both write to.
+
+test("a different transport reach changes the key", () => {
+ expect(buildCacheKey(opts({ transportReach: "local" }), "p", "fp")).not.toBe(
+ buildCacheKey(opts({ transportReach: "remote" }), "p", "fp"),
+ );
+});
+
+test("an absent transport reach keys as the narrowest, not as its own third state", () => {
+ expect(buildCacheKey(opts({}), "p", "fp")).toBe(
+ buildCacheKey(opts({ transportReach: "remote" }), "p", "fp"),
+ );
+});
+
+test("a local outcome cannot be served to a caller that established nothing", () => {
+ expect(buildCacheKey(opts({}), "p", "fp")).not.toBe(
+ buildCacheKey(opts({ transportReach: "local" }), "p", "fp"),
+ );
+});
diff --git a/tests/core/search/recall-benchmark.test.ts b/tests/core/search/recall-benchmark.test.ts
index 21c32781..40db7004 100644
--- a/tests/core/search/recall-benchmark.test.ts
+++ b/tests/core/search/recall-benchmark.test.ts
@@ -29,7 +29,8 @@ import {
runRecallBenchmark,
} from "../../../src/core/search/benchmark.ts";
import { SearchError } from "../../../src/core/search/types.ts";
-import { makeConfig } from "../../helpers/search-fixtures.ts";
+import { makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
const FIXTURE = join(import.meta.dir, "..", "..", "fixtures", "recall-benchmark");
@@ -184,3 +185,76 @@ describe("runRecallBenchmark", () => {
expect(report.hitAtK).toBeGreaterThanOrEqual(MIN_HIT_AT_5);
});
});
+
+// --- The dataset is the caller's, and so is its reach ------------------------
+//
+// `brain_benchmark` and `brain_tune` take the dataset as a required tool
+// argument over any transport, and the report answers per query with
+// `hit`, `rank`, `expectedFound` for caller-named paths and
+// `answerContained` for a caller-supplied string. The lane used to pin
+// `local` regardless.
+//
+// REFUTED, and recorded rather than dropped: that pin was NOT an oracle
+// over `visibility:`-tagged pages. `search()` also applies the caller's
+// visibility SCOPE, and the benchmark passes none, so a tagged page was
+// already outside every benchmark run at every reach - reverting the fix
+// leaves a tagged-page probe scoring absent either way.
+//
+// What the pin DID reach is the unmeasurable page: a document still in
+// the index whose file cannot be read. The reach rule substitutes the
+// reserved token for it and denies at `remote`; the caller-scope rule
+// reads its empty frontmatter as untagged and keeps it. That is the
+// difference below, and it is the whole observable difference.
+
+describe("runRecallBenchmark at the caller's reach", () => {
+ const reachVault = mkdtempSync(join(tmpdir(), "o2b-bench-reach-"));
+ const dbPath = join(reachVault, "index.sqlite");
+ let cfg: ResolvedSearchConfig;
+
+ beforeAll(async () => {
+ writeMd(reachVault, "open.md", "# Open\n\nthe payments tier rollout is staged");
+ writeMd(
+ reachVault,
+ "vanished.md",
+ "# Vanished\n\nthe payments tier rollout is staged, revised",
+ );
+ cfg = makeConfig({ vault: reachVault, dbPath });
+ await indexVault(cfg);
+ // Indexed, then gone: the routine trigger is a page deleted or
+ // renamed between runs. The document row survives, so it can still
+ // rank; only its frontmatter has become unmeasurable.
+ rmSync(join(reachVault, "vanished.md"), { force: true });
+ });
+
+ afterAll(() => rmSync(reachVault, { recursive: true, force: true }));
+
+ const probe = (expected: string) =>
+ parseRecallBenchmarkDataset({
+ queries: [{ id: "probe", query: "payments tier rollout staged", expected: [expected] }],
+ });
+
+ test("an unmeasurable page scores as absent for a caller that established nothing", async () => {
+ const report = await runRecallBenchmark(cfg, probe("vanished.md"), { k: 5 });
+ const q = report.perQuery[0]!;
+ expect(q.hit).toBe(false);
+ expect(q.rank).toBeNull();
+ expect(q.expectedFound).toBe(0);
+ });
+
+ test("a lane that established local reach still scores the whole corpus", async () => {
+ const report = await runRecallBenchmark(cfg, probe("vanished.md"), {
+ k: 5,
+ transportReach: TRANSPORT_REACH.local,
+ });
+ expect(report.perQuery[0]!.hit).toBe(true);
+ });
+
+ test("an ordinary page scores at both reaches, so the gate is not blanket-denying", async () => {
+ const reports = await Promise.all(
+ [TRANSPORT_REACH.local, TRANSPORT_REACH.remote].map((transportReach) =>
+ runRecallBenchmark(cfg, probe("open.md"), { k: 5, transportReach }),
+ ),
+ );
+ for (const report of reports) expect(report.perQuery[0]!.hit).toBe(true);
+ });
+});
diff --git a/tests/core/search/relation-polarity.test.ts b/tests/core/search/relation-polarity.test.ts
index 69587d89..22f73d65 100644
--- a/tests/core/search/relation-polarity.test.ts
+++ b/tests/core/search/relation-polarity.test.ts
@@ -22,6 +22,7 @@ import {
} from "../../../src/core/search/relation-polarity.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
import type { BrainSearchResult } from "../../../src/core/search/types.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
@@ -381,3 +382,58 @@ test("a node that is both demoted predecessor and positive target composes order
const both = forward.find((r) => r.path === "both.md")!;
expect(both.score).toBeCloseTo(0.9 * SUPERSEDED_DEMOTION + RELATION_BOOST_PER_EDGE, 5);
});
+
+// --- Root A holds across the pull-in (private-is-not-a-suggestion) ----------
+//
+// The polarity phase resolves `superseded_by` to documents that were
+// never in the filtered pool and appends their representative chunks with
+// full path, title and content. That append is downstream of every pool
+// filter, so without a second ask a public page naming a reserved
+// successor is a route to the successor's body.
+
+test("a reserved successor is not pulled into a remote caller's window", async () => {
+ writeMd(
+ vault,
+ "public-brief.md",
+ [
+ "---",
+ "title: Public brief",
+ 'superseded_by: "[[deal-terms]]"',
+ "---",
+ "# Public brief",
+ "",
+ "The blue-green rollout strategy for the payments tier.",
+ ].join("\n"),
+ );
+ writeMd(
+ vault,
+ "deal-terms.md",
+ [
+ "---",
+ "title: Deal terms",
+ "visibility: [private]",
+ "---",
+ "# Deal terms",
+ "",
+ "The blue-green rollout strategy for the payments tier, revised.",
+ ].join("\n"),
+ );
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const remote = await search(cfg, { query: "blue-green rollout payments tier", limit: 10 });
+ expect(remote.results.map((r) => r.path)).not.toContain("deal-terms.md");
+ // Not just absent from the paths: none of its body may ride out on
+ // another row either.
+ expect(JSON.stringify(remote.results)).not.toContain("revised");
+
+ // The control: the same edge, the same corpus, at a reach that reaches
+ // the page. The pull-in itself still works.
+ const local = await search(cfg, {
+ query: "blue-green rollout payments tier",
+ limit: 10,
+ visibility: ["private"],
+ transportReach: TRANSPORT_REACH.local,
+ });
+ expect(local.results.map((r) => r.path)).toContain("deal-terms.md");
+});
diff --git a/tests/core/search/schema-migration-v10.test.ts b/tests/core/search/schema-migration-v10.test.ts
index 2ca3bd8b..ac61dbc1 100644
--- a/tests/core/search/schema-migration-v10.test.ts
+++ b/tests/core/search/schema-migration-v10.test.ts
@@ -37,8 +37,8 @@ function hasColumn(db: Database, table: string, name: string): boolean {
.some((c) => c.name === name);
}
-test("latest schema version is 11", () => {
- expect(LATEST_SCHEMA_VERSION).toBe(11);
+test("latest schema version is 12", () => {
+ expect(LATEST_SCHEMA_VERSION).toBe(12);
});
test("fresh migration reaches latest with the authored_at column", () => {
diff --git a/tests/core/search/schema-migration-v11.test.ts b/tests/core/search/schema-migration-v11.test.ts
index 98f698fa..f6468e3d 100644
--- a/tests/core/search/schema-migration-v11.test.ts
+++ b/tests/core/search/schema-migration-v11.test.ts
@@ -45,8 +45,8 @@ function hasColumn(db: Database, table: string, name: string): boolean {
.some((c) => c.name === name);
}
-test("latest schema version is 11", () => {
- expect(LATEST_SCHEMA_VERSION).toBe(11);
+test("latest schema version is 12", () => {
+ expect(LATEST_SCHEMA_VERSION).toBe(12);
});
test("fresh migration reaches latest with all three event-anchor columns", () => {
diff --git a/tests/core/search/store-aliases.test.ts b/tests/core/search/store-aliases.test.ts
index a903de41..0812038b 100644
--- a/tests/core/search/store-aliases.test.ts
+++ b/tests/core/search/store-aliases.test.ts
@@ -53,8 +53,8 @@ function targetDocId(store: Store, sourceId: number): number | null {
return row?.target_document_id ?? null;
}
-test("schema version is 11", () => {
- expect(LATEST_SCHEMA_VERSION).toBe(11);
+test("schema version is 12", () => {
+ expect(LATEST_SCHEMA_VERSION).toBe(12);
});
test("normalizeAlias lower-cases, trims, and NFC-normalises", () => {
diff --git a/tests/core/search/visibility-column-backfill.test.ts b/tests/core/search/visibility-column-backfill.test.ts
new file mode 100644
index 00000000..ba397c31
--- /dev/null
+++ b/tests/core/search/visibility-column-backfill.test.ts
@@ -0,0 +1,192 @@
+/**
+ * `documents.visibility`, and the migration that fills it for an index
+ * that predates it (private-is-not-a-suggestion, unit 6).
+ *
+ * The consultant's recommended shape was "a missing column value means
+ * private, and the legacy population self-heals". Verified against
+ * source, that is a total search blackout: `applyMigrations` adds a
+ * column with NULL for every existing row, so on upgrade every document
+ * in every vault - including the overwhelming majority that have never
+ * used `visibility:` at all - would answer as reserved until a full
+ * reindex. This file is the executable form of the correction: the
+ * migration BACKFILLS, from the frontmatter the index already stores as
+ * its own chunk at `chunk_index = 0`.
+ *
+ * Three column states, all three distinct:
+ *
+ * - a JSON array of the page's normalised tokens - measured;
+ * - `[]` - measured, and the page declares none;
+ * - NULL - the index cannot measure this document, which is a third
+ * state and not a synonym for the second.
+ *
+ * ## One premise of the plan, refuted here
+ *
+ * The plan expected an UNTERMINATED frontmatter block to land in the
+ * third state. It cannot: `chunker.ts`'s `readFrontmatter` drops the
+ * opening `---` and keeps the rest as body, so chunk zero of such a page
+ * is byte-indistinguishable from chunk zero of a page with no
+ * frontmatter at all, and no reader of the index can tell them apart.
+ *
+ * It also does not matter, which is why the correction is a rewording
+ * rather than a redesign: `parseFrontmatterText` reads an unterminated
+ * block on the REAL FILE as declaring nothing too, so the column and the
+ * live boundary at the three read roots agree. The third state is
+ * therefore what it says it is - a document the index holds no chunk
+ * zero for - and it is pinned below from that shape rather than from an
+ * unterminated block.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../../src/core/graph/visibility.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import {
+ DOCUMENT_VISIBILITY_COLUMN,
+ LATEST_SCHEMA_VERSION,
+ applyMigrations,
+ readSchemaVersion,
+} from "../../../src/core/search/schema.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+/** The schema version this column was introduced at. */
+const PRE_COLUMN_SCHEMA_VERSION = 11;
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ ({ vault, dbPath, cleanup } = createTempVault("visibility-column"));
+});
+afterEach(() => cleanup());
+
+/**
+ * Rewind a freshly built index to the schema this column was added at, so
+ * the migration runs over rows an older binary wrote. Dropping the column
+ * and the version stamp together is exactly the state such an index is in.
+ */
+function rewindToPreColumnSchema(): void {
+ const db = new Database(dbPath);
+ try {
+ db.exec(`ALTER TABLE documents DROP COLUMN ${DOCUMENT_VISIBILITY_COLUMN}`);
+ db.query("UPDATE index_state SET value = ? WHERE key = 'schema_version'").run(
+ String(PRE_COLUMN_SCHEMA_VERSION),
+ );
+ } finally {
+ db.close();
+ }
+}
+
+function visibilityByPath(): Map<string, string | null> {
+ const db = new Database(dbPath, { readonly: true });
+ try {
+ const rows = db
+ .query<{ path: string; visibility: string | null }, []>(
+ `SELECT path, ${DOCUMENT_VISIBILITY_COLUMN} AS visibility FROM documents`,
+ )
+ .all();
+ return new Map(rows.map((r) => [r.path, r.visibility]));
+ } finally {
+ db.close();
+ }
+}
+
+function migrate(): number {
+ const db = new Database(dbPath);
+ try {
+ return applyMigrations(db);
+ } finally {
+ db.close();
+ }
+}
+
+async function seedThreeStates(): Promise<void> {
+ writeMd(vault, "plain.md", "# Plain\n\nlattice widget ordinary");
+ writeMd(
+ vault,
+ "reserved.md",
+ `---\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]\n---\n# Reserved\n\nlattice widget reserved`,
+ );
+ // An unterminated block declares nothing, on the file and in the index
+ // alike - see the module docblock.
+ writeMd(vault, "unterminated.md", "---\nvisibility: [team]\n\n# Broken\n\nlattice widget broken");
+ await indexVault(makeConfig({ vault, dbPath }));
+}
+
+describe("the migration over a pre-column index", () => {
+ test("backfills the three states from the frontmatter the index already holds", async () => {
+ await seedThreeStates();
+ rewindToPreColumnSchema();
+ expect(migrate()).toBe(LATEST_SCHEMA_VERSION);
+
+ const byPath = visibilityByPath();
+ expect(byPath.get("plain.md")).toBe("[]");
+ expect(byPath.get("reserved.md")).toBe(JSON.stringify([REMOTE_DENY_VISIBILITY_TOKEN]));
+ expect(byPath.get("unterminated.md")).toBe("[]");
+ });
+
+ test("leaves a document the index holds no chunk zero for unmeasured", async () => {
+ await seedThreeStates();
+ rewindToPreColumnSchema();
+ // A row an older binary wrote whose chunks are gone: the index holds
+ // nothing to measure, and "no tokens" would be a claim nobody made.
+ const db = new Database(dbPath);
+ try {
+ db.query(
+ "DELETE FROM chunks WHERE document_id = (SELECT id FROM documents WHERE path = ?)",
+ ).run("plain.md");
+ } finally {
+ db.close();
+ }
+ migrate();
+ expect(visibilityByPath().get("plain.md")).toBeNull();
+ });
+
+ test("leaves a vault that never used the field answering identically", async () => {
+ writeMd(vault, "a.md", "# A\n\nlattice alpha");
+ writeMd(vault, "b.md", "# B\n\nlattice beta");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+ const before = await search(cfg, { query: "lattice", limit: 10 });
+
+ rewindToPreColumnSchema();
+ migrate();
+
+ const after = await search(cfg, { query: "lattice", limit: 10 });
+ expect(after.results.map((r) => r.path)).toEqual(before.results.map((r) => r.path));
+ expect([...visibilityByPath().values()]).toEqual(["[]", "[]"]);
+ });
+
+ test("is idempotent: migrating an already-current index changes nothing", async () => {
+ await seedThreeStates();
+ const first = visibilityByPath();
+ expect(migrate()).toBe(LATEST_SCHEMA_VERSION);
+ expect(visibilityByPath()).toEqual(first);
+ });
+});
+
+describe("the indexer", () => {
+ test("writes the column on every upsert, without a migration", async () => {
+ await seedThreeStates();
+ const db = new Database(dbPath, { readonly: true });
+ try {
+ expect(readSchemaVersion(db)).toBe(LATEST_SCHEMA_VERSION);
+ } finally {
+ db.close();
+ }
+ const byPath = visibilityByPath();
+ expect(byPath.get("plain.md")).toBe("[]");
+ expect(byPath.get("reserved.md")).toBe(JSON.stringify([REMOTE_DENY_VISIBILITY_TOKEN]));
+ expect(byPath.get("unterminated.md")).toBe("[]");
+ });
+
+ test("normalises the stored tokens the way the predicate compares them", async () => {
+ writeMd(vault, "mixed.md", "---\nvisibility: [' Private ', TEAM]\n---\n\nlattice widget");
+ await indexVault(makeConfig({ vault, dbPath }));
+ expect(visibilityByPath().get("mixed.md")).toBe(
+ JSON.stringify([REMOTE_DENY_VISIBILITY_TOKEN, "team"]),
+ );
+ });
+});
diff --git a/tests/core/search/visibility-filter.test.ts b/tests/core/search/visibility-filter.test.ts
index e4cf859e..60186908 100644
--- a/tests/core/search/visibility-filter.test.ts
+++ b/tests/core/search/visibility-filter.test.ts
@@ -9,13 +9,17 @@
import { test, expect, beforeEach, afterEach, describe } from "bun:test";
import {
+ REMOTE_DENY_VISIBILITY_TOKEN,
isVisible,
normalizeVisibilityScope,
pageVisibility,
} from "../../../src/core/graph/visibility.ts";
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
describe("visibility rule (pure)", () => {
test("a page with no visibility tag is always reachable", () => {
@@ -57,15 +61,63 @@ describe("visibility scoping in search", () => {
const defPaths = def.results.map((r) => r.path).toSorted();
expect(defPaths).toEqual(["public.md"]);
+ // The caller argument still lifts the page for a caller this server
+ // established local access for - the operator's own CLI, unchanged.
const scoped = await search(cfg, {
query: "lattice widgets",
limit: 10,
- visibility: ["private"],
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ transportReach: TRANSPORT_REACH.local,
});
const scopedPaths = scoped.results.map((r) => r.path).toSorted();
expect(scopedPaths).toEqual(["public.md", "secret.md"]);
});
+ test("the caller argument narrows only: it cannot lift the reserved token", async () => {
+ writeMd(vault, "public.md", "# Public\n\nshared lattice notes about widgets");
+ writeMd(
+ vault,
+ "secret.md",
+ "---\nvisibility: [private]\n---\n# Secret\n\nclassified lattice notes about widgets",
+ );
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const asked = await search(cfg, {
+ query: "lattice widgets",
+ limit: 10,
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ transportReach: TRANSPORT_REACH.remote,
+ });
+ expect(asked.results.map((r) => r.path).toSorted()).toEqual(["public.md"]);
+ });
+
+ test("an unmeasurable page is withheld at remote reach and kept at local", async () => {
+ // A document still in the index whose file was deleted since the last
+ // run has an UNREADABLE visibility claim, and an unreadable claim is
+ // not the absence of one. Fail closed at remote reach; the local
+ // caller, who could read the file directly anyway, keeps the row.
+ writeMd(vault, "gone.md", "# Gone\n\nlattice widget vanishing");
+ writeMd(vault, "here.md", "# Here\n\nlattice widget staying");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+ rmSync(join(vault, "gone.md"));
+
+ const remote = await search(cfg, {
+ query: "lattice widget",
+ limit: 10,
+ transportReach: TRANSPORT_REACH.remote,
+ });
+ expect(remote.results.map((r) => r.path).toSorted()).toEqual(["here.md"]);
+
+ const local = await search(cfg, {
+ query: "lattice widget",
+ limit: 10,
+ transportReach: TRANSPORT_REACH.local,
+ });
+ expect(local.results.map((r) => r.path).toSorted()).toEqual(["gone.md", "here.md"]);
+ });
+
test("default scope backfills untagged matches when tagged pages crowd a narrow pool", async () => {
// Recall layers off (mmrLambda=1, maxHops=0) -> the narrow rank cap
// would otherwise let tagged pages truncate the window below `limit`.
@@ -89,6 +141,56 @@ describe("visibility scoping in search", () => {
expect(out.results.every((r) => r.path.startsWith("public-"))).toBe(true);
});
+ test("the retrieval trail never counts what the reserved-token rule withheld", async () => {
+ // The trail answers "did MY scope remove my results". The reach rule
+ // is not a scope the caller requested, so a count of its drops would
+ // tell this caller that pages it may not read matched its query -
+ // the existence oracle a withheld page is supposed to be free of.
+ writeMd(vault, "reserved.md", "---\nvisibility: [private]\n---\nlattice widget reserved");
+ writeMd(vault, "open.md", "# Open\n\nlattice widget open");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const remote = await search(cfg, { query: "lattice widget", limit: 10 });
+ expect(remote.results.map((r) => r.path)).toEqual(["open.md"]);
+ const codes = (remote.retrievalTrail?.degraded ?? []).map((d) => d.code);
+ expect(codes).not.toContain("scope-filters-dropped-rows");
+
+ // The local half is the control: the same corpus reaches both pages
+ // once the caller's own scope names the token too - the reach rule
+ // and the caller-scope rule are independent, and BOTH have to admit
+ // the page. Still nothing to report as narrowing.
+ const local = await search(cfg, {
+ query: "lattice widget",
+ limit: 10,
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ transportReach: TRANSPORT_REACH.local,
+ });
+ expect(local.results.map((r) => r.path).toSorted()).toEqual(["open.md", "reserved.md"]);
+ expect((local.retrievalTrail?.degraded ?? []).map((d) => d.code)).not.toContain(
+ "scope-filters-dropped-rows",
+ );
+ });
+
+ test("a scope the caller DID request is still reported as narrowing", async () => {
+ // The counterweight to the test above: removing the reach drop from
+ // the trail must not silence the narrowing the trail exists for.
+ writeMd(vault, "team.md", "---\nvisibility: [team]\n---\nlattice widget team");
+ writeMd(vault, "open.md", "# Open\n\nlattice widget open");
+ const cfg = makeConfig({ vault, dbPath });
+ await indexVault(cfg);
+
+ const out = await search(cfg, {
+ query: "lattice widget",
+ limit: 10,
+ visibility: ["some-other-token"],
+ });
+ expect(out.results.map((r) => r.path)).toEqual(["open.md"]);
+ expect((out.retrievalTrail?.degraded ?? []).map((d) => d.code)).toContain(
+ "scope-filters-dropped-rows",
+ );
+ });
+
test("an all-untagged vault is unaffected by the default scope", async () => {
writeMd(vault, "a.md", "# A\n\nlattice alpha");
writeMd(vault, "b.md", "# B\n\nlattice beta");
diff --git a/tests/core/search/visibility-honesty-finding.test.ts b/tests/core/search/visibility-honesty-finding.test.ts
index 01122834..ad97aa97 100644
--- a/tests/core/search/visibility-honesty-finding.test.ts
+++ b/tests/core/search/visibility-honesty-finding.test.ts
@@ -66,6 +66,28 @@ test("a vault with one visibility-tagged page gets the finding, counted from the
expect(report.visibilityHonesty?.totalSurfaceCount).toBe(callableVisibilitySurfaces().length);
// Not a trivial zero-of-zero: the registry actually carries excluded rows.
expect(report.visibilityHonesty!.excludedSurfaceCount).toBeGreaterThan(0);
+ // ...and the covered half is no longer the two surfaces it started as.
+ // `total > excluded` only says the covered half is at least ONE, which
+ // this wave's whole claim is that it is not - so the assertion is
+ // against the number the wave inherited, not against zero.
+ const COVERED_BEFORE_THIS_WAVE = 2;
+ const covered =
+ report.visibilityHonesty!.totalSurfaceCount - report.visibilityHonesty!.excludedSurfaceCount;
+ expect(covered).toBeGreaterThan(COVERED_BEFORE_THIS_WAVE);
+});
+
+test("the document counts come from the index, not from a hand-written number", async () => {
+ writeMd(vault, "open.md", "# Open\n\nAn ordinary note.");
+ writeMd(vault, "a.md", "---\nvisibility: private\n---\n\n# A\n\nA reserved page.");
+ writeMd(vault, "b.md", "---\nvisibility: private\n---\n\n# B\n\nAnother reserved page.");
+ writeMd(vault, "team.md", "---\nvisibility: team\n---\n\n# T\n\nA team page.");
+ await indexVault(makeConfig({ vault, dbPath }));
+
+ const report = await indexCheck(makeConfig({ vault, dbPath }));
+ // Only the reserved token counts - a non-reserved one is not withheld.
+ expect(report.visibilityHonesty?.reservedDocumentCount).toBe(2);
+ // Every page here has a frontmatter chunk the index could read.
+ expect(report.visibilityHonesty?.unmeasuredDocumentCount).toBe(0);
});
test("the denominator leaves out the row the registry itself calls not a surface", async () => {
diff --git a/tests/core/search/visibility-tag-presence.test.ts b/tests/core/search/visibility-tag-presence.test.ts
index 26452b6a..4a06432d 100644
--- a/tests/core/search/visibility-tag-presence.test.ts
+++ b/tests/core/search/visibility-tag-presence.test.ts
@@ -25,7 +25,8 @@ import { mkdirSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { indexVault } from "../../../src/core/search/indexer.ts";
-import { peekVisibilityTagPresence } from "../../../src/core/search/store/visibility-tag.ts";
+import { peekVisibilityColumnCensus } from "../../../src/core/search/store/visibility-tag.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../../src/core/graph/visibility.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
let vault: string;
@@ -48,9 +49,9 @@ test("a vault with no visibility frontmatter anywhere reads absent", async () =>
writeMd(vault, "b.md", "---\ntitle: B\n---\n\n# B\n\nTagged with an unrelated key.");
await indexVault(makeConfig({ vault, dbPath }));
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("read");
- if (peek.kind === "read") expect(peek.value).toBe(false);
+ if (peek.kind === "read") expect(peek.value.tagged).toBe(false);
});
test("a vault with one visibility-tagged page reads present", async () => {
@@ -58,9 +59,9 @@ test("a vault with one visibility-tagged page reads present", async () => {
writeMd(vault, "b.md", "---\nvisibility: private\n---\n\n# B\n\nA private page.");
await indexVault(makeConfig({ vault, dbPath }));
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("read");
- if (peek.kind === "read") expect(peek.value).toBe(true);
+ if (peek.kind === "read") expect(peek.value.tagged).toBe(true);
});
test("the word 'visibility' in body prose, with no 'visibility:' key text, does not flip the peek", async () => {
@@ -71,18 +72,20 @@ test("the word 'visibility' in body prose, with no 'visibility:' key text, does
);
await indexVault(makeConfig({ vault, dbPath }));
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("read");
- if (peek.kind === "read") expect(peek.value).toBe(false);
+ if (peek.kind === "read") expect(peek.value.tagged).toBe(false);
});
-test("a 'visibility:' phrase in body prose (no frontmatter block) still flips the peek, by design", async () => {
- // The documented imprecision is not scoped to frontmatter VALUES: the
- // heuristic reads chunk_index 0 wholesale, and a page with no
- // frontmatter block puts its own first content chunk there. A body
- // line spelling the exact key phrase is charged as a false positive
- // for the same reason a quoted title would be - pinned here as the
- // shape of the tradeoff, not as an oversight to close.
+test("a 'visibility:' phrase in body prose no longer flips the peek", async () => {
+ // The tradeoff this case used to pin is GONE, and its removal is the
+ // point rather than a side effect. The answer came from a
+ // `LIKE '%visibility:%'` scan of chunk zero, which a page with no
+ // frontmatter fills with its own first content chunk - so a body line
+ // spelling the key phrase was charged as a tagged vault, exactly as a
+ // quoted title was. It is now read off `documents.visibility`, decided
+ // by the same `pageVisibility` the read boundary uses, so prose cannot
+ // declare anything.
writeMd(
vault,
"a.md",
@@ -90,19 +93,28 @@ test("a 'visibility:' phrase in body prose (no frontmatter block) still flips th
);
await indexVault(makeConfig({ vault, dbPath }));
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("read");
- if (peek.kind === "read") expect(peek.value).toBe(true);
+ if (peek.kind === "read") expect(peek.value.tagged).toBe(false);
+});
+
+test("a frontmatter VALUE quoting the key no longer flips it either", async () => {
+ writeMd(vault, "a.md", '---\ntitle: "on visibility: a note"\n---\n\n# A\n\nBody.');
+ await indexVault(makeConfig({ vault, dbPath }));
+
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
+ expect(peek.kind).toBe("read");
+ if (peek.kind === "read") expect(peek.value.tagged).toBe(false);
});
test("an absent index reads absent, never a false folded into a read", () => {
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("absent");
});
test("a file that is not a readable index reads unreadable with the open's reason", () => {
mkdirSync(dirname(dbPath), { recursive: true });
writeFileSync(dbPath, "not a database");
- const peek = peekVisibilityTagPresence(dbPath);
+ const peek = peekVisibilityColumnCensus(dbPath, REMOTE_DENY_VISIBILITY_TOKEN);
expect(peek.kind).toBe("unreadable");
});
diff --git a/tests/core/vault.test.ts b/tests/core/vault.test.ts
index 83d3f551..7a917376 100644
--- a/tests/core/vault.test.ts
+++ b/tests/core/vault.test.ts
@@ -24,6 +24,7 @@ import {
slugify,
writeFrontmatter,
} from "../../src/core/vault.ts";
+import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
let tmp: string;
@@ -382,11 +383,18 @@ describe("extractWikilinks", () => {
});
});
+/**
+ * None of these pages carries the reserved visibility token, so the walk
+ * answers identically at either reach; the cases that DO turn on it live
+ * in `tests/core/vault/list-vault-pages-visibility.test.ts`.
+ */
+const REACH_AGNOSTIC = TRANSPORT_REACH.local;
+
describe("listVaultPages", () => {
test("discovers Markdown files", () => {
writeFileSync(join(tmp, "page1.md"), "---\ntitle: Alpha\n---\n\nContent.");
writeFileSync(join(tmp, "page2.md"), "Beta content without frontmatter.");
- const pages = listVaultPages(tmp);
+ const pages = listVaultPages(tmp, { reach: REACH_AGNOSTIC });
expect(pages.length).toBe(2);
const titles = pages.map((p) => p.title);
expect(titles).toContain("Alpha");
@@ -397,13 +405,13 @@ describe("listVaultPages", () => {
writeFileSync(join(tmp, "page.md"), "Content.");
mkdirSync(join(tmp, ".obsidian"));
writeFileSync(join(tmp, ".obsidian", "hidden.md"), "Hidden.");
- expect(listVaultPages(tmp).length).toBe(1);
+ expect(listVaultPages(tmp, { reach: REACH_AGNOSTIC }).length).toBe(1);
});
test("skips excluded files (index.md, log.md)", () => {
writeFileSync(join(tmp, "page.md"), "Content.");
writeFileSync(join(tmp, "index.md"), "Index.");
- const pages = listVaultPages(tmp);
+ const pages = listVaultPages(tmp, { reach: REACH_AGNOSTIC });
expect(pages.length).toBe(1);
expect(pages[0]!.title).toBe("page");
});
@@ -412,7 +420,7 @@ describe("listVaultPages", () => {
writeFileSync(join(tmp, "clean.md"), "---\ntitle: Alpha\ntags:\n - a\n---\n\nContent.");
writeFileSync(join(tmp, "odd.md"), "---\ntitle: Beta\n-foo\n---\n\nContent.");
const notices: DegradationNotice[] = [];
- const pages = listVaultPages(tmp, { notices });
+ const pages = listVaultPages(tmp, { notices, reach: REACH_AGNOSTIC });
// Control flow unchanged: the odd page is still listed.
expect(pages.length).toBe(2);
expect(notices).toHaveLength(1);
@@ -424,7 +432,7 @@ describe("listVaultPages", () => {
writeFileSync(join(tmp, "clean.md"), "---\ntitle: Alpha\ntags:\n - a\n---\n\nContent.");
writeFileSync(join(tmp, "plain.md"), "No frontmatter at all.");
const notices: DegradationNotice[] = [];
- listVaultPages(tmp, { notices });
+ listVaultPages(tmp, { notices, reach: REACH_AGNOSTIC });
expect(notices).toEqual([]);
});
@@ -436,7 +444,7 @@ describe("listVaultPages", () => {
chmodSync(locked, 0o000);
const notices: DegradationNotice[] = [];
try {
- const pages = listVaultPages(tmp, { notices });
+ const pages = listVaultPages(tmp, { notices, reach: REACH_AGNOSTIC });
// Same control flow as before: the unreadable subtree is skipped.
expect(pages.length).toBe(1);
expect(notices).toHaveLength(1);
diff --git a/tests/core/vault/list-vault-pages-visibility.test.ts b/tests/core/vault/list-vault-pages-visibility.test.ts
new file mode 100644
index 00000000..688e8071
--- /dev/null
+++ b/tests/core/vault/list-vault-pages-visibility.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Root B: the vault page walker honours the reserved visibility token
+ * (private-is-not-a-suggestion, unit 4).
+ *
+ * `listVaultPages` is the second of the three roots every callable
+ * surface reaches page content through. It already parses each page's
+ * frontmatter, so the decision costs no extra read - the shape
+ * `vaultPageInStatusScope` established for entity status.
+ *
+ * The reach is a REQUIRED option rather than a defaulted one: an internal
+ * maintenance lane that quietly stopped seeing reserved pages would
+ * corrupt the graph it repairs, and a read surface that quietly saw them
+ * would be the boundary failing. Neither is a decision to make by
+ * omission.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { TRANSPORT_REACH } from "../../../src/core/graph/transport-reach.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../../src/core/graph/visibility.ts";
+import { listVaultPages } from "../../../src/core/vault.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "list-vault-pages-vis-"));
+ writeFileSync(join(vault, "open.md"), "---\ntitle: Open\n---\n\nordinary body");
+ writeFileSync(
+ join(vault, "reserved.md"),
+ `---\ntitle: Reserved\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]\n---\n\nreserved body`,
+ );
+ writeFileSync(join(vault, "team.md"), "---\ntitle: Team\nvisibility: [team]\n---\n\nteam body");
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+function titles(reach: (typeof TRANSPORT_REACH)[keyof typeof TRANSPORT_REACH]): string[] {
+ return listVaultPages(vault, { reach })
+ .map((p) => p.title)
+ .toSorted();
+}
+
+describe("listVaultPages", () => {
+ test("withholds a page carrying the reserved token at remote reach", () => {
+ expect(titles(TRANSPORT_REACH.remote)).toEqual(["Open", "Team"]);
+ });
+
+ test("lists every page at local reach", () => {
+ expect(titles(TRANSPORT_REACH.local)).toEqual(["Open", "Reserved", "Team"]);
+ });
+
+ test("leaves a non-reserved token alone at both reaches", () => {
+ // Non-reserved tokens keep exactly today's caller-liftable scoping
+ // semantics; this walker defines no policy for them.
+ for (const reach of [TRANSPORT_REACH.local, TRANSPORT_REACH.remote]) {
+ expect(titles(reach)).toContain("Team");
+ }
+ });
+
+ test("a vault that never wrote the token is identical at both reaches", () => {
+ rmSync(join(vault, "reserved.md"));
+ expect(titles(TRANSPORT_REACH.remote)).toEqual(titles(TRANSPORT_REACH.local));
+ });
+});
+
+// --- The unmeasurable page: one rule, one fail direction ---------------------
+//
+// The three roots have to agree about the page they cannot read. Roots A
+// and C substitute the reserved token for it (`isPathReadableAtReach`);
+// root B used to read its empty parsed map as "declares nothing" and
+// admit it at remote reach, which is the same rule failing in two
+// directions on the same input.
+
+describe("a page whose file cannot be read", () => {
+ const unreadable = (): string => {
+ const path = join(vault, "unreadable.md");
+ writeFileSync(path, "---\ntitle: Unreadable\n---\n\nbody");
+ chmodSync(path, 0o000);
+ return path;
+ };
+
+ test("is withheld at remote reach, exactly as a reserved page is", () => {
+ const path = unreadable();
+ try {
+ const walked = listVaultPages(vault, { reach: TRANSPORT_REACH.remote }).map((p) => p.title);
+ expect(walked).not.toContain("unreadable");
+ expect(walked).not.toContain("Unreadable");
+ } finally {
+ chmodSync(path, 0o644);
+ }
+ });
+
+ test("is kept at local reach, where the caller can open the file itself", () => {
+ const path = unreadable();
+ try {
+ const walked = listVaultPages(vault, { reach: TRANSPORT_REACH.local }).map((p) => p.title);
+ expect(walked).toContain("unreadable");
+ } finally {
+ chmodSync(path, 0o644);
+ }
+ });
+
+ test("a readable untagged page is unaffected at both reaches", () => {
+ for (const reach of [TRANSPORT_REACH.local, TRANSPORT_REACH.remote] as const) {
+ expect(listVaultPages(vault, { reach }).map((p) => p.title)).toContain("Open");
+ }
+ });
+});
diff --git a/tests/helpers/tool-probe-catalogue.ts b/tests/helpers/tool-probe-catalogue.ts
new file mode 100644
index 00000000..7f282df2
--- /dev/null
+++ b/tests/helpers/tool-probe-catalogue.ts
@@ -0,0 +1,1076 @@
+/**
+ * Every tool in the live table, with the arguments that DRIVE each of its
+ * code paths - the one enumeration two isolation axes share.
+ *
+ * It was `tests/mcp/agent-scope-matrix.test.ts`'s alone until a second
+ * axis needed it. `tests/mcp/visibility-matrix.test.ts` asks a different
+ * question of the same surface - may a caller at this transport reach see
+ * this page, rather than may this owner see this artifact - and a second
+ * copy of the recipes would have been a second answer to "what is the
+ * whole surface", which is precisely the enumeration defect the owner
+ * matrix was built to remove.
+ *
+ * What lives here is the INVOCATION: the tool name, the arguments each of
+ * its code paths needs, and the fixture constants those arguments quote.
+ * The owner-axis CLASSIFICATION ({@link REASON} and the two buckets it
+ * sorts calls into) lives here too, because a reason is per-call and the
+ * calls are here; the visibility axis carries its own classification in
+ * its own file rather than borrowing this one's.
+ *
+ * Data and pure helpers only - no `test()`, no fixture seeding, no
+ * `beforeEach`. A test file importing another test file would run that
+ * file's suite twice.
+ */
+
+import { runHygieneScan } from "../../src/core/brain/hygiene/scan.ts";
+import { scanTriggers } from "../../src/core/brain/triggers/scan.ts";
+import { transitionTrigger } from "../../src/core/brain/triggers/store.ts";
+
+export const OWNER_A = "agent-a";
+export const OWNER_B = "agent-b";
+export const QUERY = "lattice widgets";
+/** Probe path whose derived query terms appear verbatim in every note. */
+export const PROBE = "lattice.md";
+export const PROBE_TERMS = `${PROBE} lattice`;
+
+/**
+ * The string the isolation probe hunts for.
+ *
+ * It appears ONLY inside artifacts owned by {@link OWNER_A} - in their
+ * ids, their paths, their topics, their titles and their body prose - so
+ * one `not.toContain` catches every channel a surface might use to name
+ * one of them, without the probe having to know which field carried it.
+ */
+export const CROSS_OWNER_MARKER = "secretmarkerzz";
+
+/** The UTC day the fixture's log event lands on; `brain_event_trace` selects by date. */
+export const LOG_EVENT_DATE = "2026-05-04";
+
+/** Shared hub the fixture's MOC audit is driven against. */
+export const HUB_ID = "pref-hub";
+/** Shared preference every owner-A artifact references, and the probe's link target. */
+export const SHARED_ID = "pref-shared";
+/** Title of {@link SHARED_ID}; the term `brain_unlinked_mentions` matches on. */
+export const SHARED_TITLE = "Shared Pref";
+/**
+ * Topic of {@link SHARED_ID}, and deliberately ALSO the topic of one
+ * owner-A preference.
+ *
+ * A `topic:` argument is a fan-out: `buildBeliefEvolution` resolves it to
+ * every `pref-`/`ret-` page carrying that topic, so a caller naming a
+ * topic it is entitled to still reaches preferences it is not. Probing
+ * that with a marker-bearing topic would prove nothing - the marker
+ * would be the caller's own argument echoed back.
+ */
+export const SHARED_TOPIC = "shared";
+/** Slug of the ownerless signal that evidences the owner-A preference. */
+export const NEUTRAL_SIGNAL_SLUG = "neutral-probe-signal";
+
+/** How a surface learns which agent is asking. */
+export const SCOPE_SOURCE = Object.freeze({
+ /** An explicit `agent_scope` input argument. */
+ argument: "argument",
+ /** `ServerContext.agentName`, for a surface that takes no arguments. */
+ serverIdentity: "server-identity",
+} as const);
+
+export type ScopeSource = (typeof SCOPE_SOURCE)[keyof typeof SCOPE_SOURCE];
+
+export interface ScopedSurface {
+ readonly name: string;
+ readonly source: ScopeSource;
+ /**
+ * True when isolation is behind `integrity.owner_scope_delivery`.
+ * Preference-backed surfaces are gated (their scope may be defaulted
+ * from the server identity, which would narrow a vault that never
+ * opted in). Search-backed surfaces are not: their scope only ever
+ * arrives as an explicit per-call argument, so honouring it cannot
+ * narrow anything the caller did not ask to narrow.
+ */
+ readonly gated: boolean;
+}
+
+/** Content-returning tools that consult the ownership rule. */
+export const SCOPED_SURFACES: ReadonlyArray<ScopedSurface> = [
+ { name: "brain_context", source: SCOPE_SOURCE.serverIdentity, gated: true },
+ { name: "brain_context_pack", source: SCOPE_SOURCE.argument, gated: true },
+ { name: "brain_pre_compress_pack", source: SCOPE_SOURCE.argument, gated: true },
+ { name: "brain_anticipatory_context", source: SCOPE_SOURCE.argument, gated: true },
+ { name: "brain_brief", source: SCOPE_SOURCE.argument, gated: true },
+ { name: "brain_retrieval_plan", source: SCOPE_SOURCE.argument, gated: true },
+ { name: "brain_query", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_search", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_search_expand", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_file_context", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_deep_synthesis", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_search_by_source", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "second_brain_query", source: SCOPE_SOURCE.argument, gated: false },
+ { name: "brain_agent_query", source: SCOPE_SOURCE.argument, gated: false },
+];
+
+/**
+ * One probe recipe: the arguments that DRIVE one mode / view / operation
+ * of a tool against the two-owner fixture, and a written reason for the
+ * classification THAT CALL carries.
+ *
+ * The reason lives on the call rather than on the tool because a tool is
+ * not one classification. `brain_analytics view=concept_synthesis`
+ * reaches another owner's body prose and `view=dedup` reaches an ingest
+ * counter; one entry claiming one reason for both is the same
+ * unexecuted label this file exists to remove, and it is how
+ * `concept_synthesis` shipped unfiltered behind a green `view=timeline`.
+ */
+
+export interface ProbeCall {
+ /**
+ * Arguments the isolation probe calls the tool with, or a function of
+ * the vault that computes them after the fixture is seeded.
+ *
+ * `{}` only where the tool's input schema declares no property the
+ * probe needs, never as a stand-in for "I did not work out what
+ * drives this one". The function form exists for the one recipe whose
+ * arguments are derived from vault state - `brain_hygiene mode=apply`
+ * selects findings by id, and a static id would drive a call that
+ * matches nothing.
+ */
+ readonly args: Record<string, unknown> | ((vault: string) => Record<string, unknown>);
+ /** Why THIS call sits in the bucket it sits in. */
+ readonly reason: string;
+ /**
+ * Test-name suffix for a recipe whose arguments are computed, where
+ * the dispatch key cannot be read off a literal record.
+ */
+ readonly label?: string;
+}
+
+/** One tool, and every call recipe the probe drives it with. */
+export interface ProbeEntry {
+ readonly name: string;
+ readonly calls: ReadonlyArray<ProbeCall>;
+}
+
+/** A single-recipe entry, spelled without the array ceremony. */
+export function one(args: ProbeCall["args"], reason: string): ReadonlyArray<ProbeCall> {
+ return [{ args, reason }];
+}
+
+/**
+ * Shortest reason this file accepts. A one-word reason is the bare name
+ * list with extra punctuation, so the floor is set above it.
+ */
+export const REASON_MIN_CHARS = 24;
+
+/**
+ * Refuse an entry that carries no call recipes or no reason.
+ *
+ * `unknown` rather than {@link ProbeEntry}: the compiler already rejects
+ * a bare name, and this is the second lock, for a `satisfies`-free cast
+ * or a bucket built at runtime. It runs at module load over every entry,
+ * so a nameless-args entry fails the whole file rather than one test.
+ */
+export function assertProbeEntry(bucket: string, entry: unknown): ProbeEntry {
+ if (typeof entry !== "object" || entry === null) {
+ throw new Error(`${bucket}: every entry must be a {name, calls} record`);
+ }
+ const row = entry as Partial<ProbeEntry>;
+ if (typeof row.name !== "string" || row.name.length === 0) {
+ throw new Error(`${bucket}: every entry must name a tool`);
+ }
+ if (!Array.isArray(row.calls) || row.calls.length === 0) {
+ throw new Error(
+ `${bucket}: ${row.name} has no 'calls'; a bucket entry the probe cannot call is a label`,
+ );
+ }
+ for (const recipe of row.calls) {
+ const shaped = recipe as Partial<ProbeCall>;
+ const args = shaped.args;
+ const argsOk =
+ typeof args === "function" ||
+ (typeof args === "object" && args !== null && !Array.isArray(args));
+ if (!argsOk) {
+ throw new Error(
+ `${bucket}: ${row.name} has a call with no 'args'; a recipe the probe cannot call is a label`,
+ );
+ }
+ if (typeof shaped.reason !== "string" || shaped.reason.trim().length < REASON_MIN_CHARS) {
+ throw new Error(
+ `${bucket}: ${row.name} needs a reason of at least ${REASON_MIN_CHARS} characters`,
+ );
+ }
+ }
+ return row as ProbeEntry;
+}
+
+/**
+ * Reasons shared by more than one call, named once.
+ *
+ * The alternative - hundreds of hand-written sentences, most of them
+ * saying the same thing in different words - is the natural-language
+ * word list this repository forbids, and it would make two calls with
+ * the same classification look like two different classifications.
+ *
+ * Each of these is a CLAIM the differential below executes. Every reason
+ * except {@link REASON.ownerFiltered} asserts that the call cannot name
+ * an owner-private artifact AT ALL, so the probe requires the marker to
+ * be absent even with the gate OFF, where nothing is hidden. A call that
+ * surfaces the marker unscoped has a false reason and fails here, which
+ * is the difference between a classification and a label.
+ */
+export const REASON = Object.freeze({
+ sessionLane:
+ "session transcript lane: the records are keyed by session and turn, not by an " +
+ "owner-taggable page, so `pageOwner` has no subject to read.",
+ catalog:
+ "a catalog of this server's own surface - the tool table, the skills manifest, the " +
+ "preset list - answered without opening a vault page, so no page's owner is reachable.",
+ writerEcho:
+ "a writer: the response echoes the artifact this very call created, planned or refused, " +
+ "so the only ownership it can name is the one the caller supplied.",
+ callerNamedArtifact:
+ "answers only about the artifact the caller already named, and every response shape it " +
+ "can produce is distinguishable from a refusal - so a filter here would announce the " +
+ "existence of the page it is meant to hide.",
+ ownerlessLane:
+ "reads a lane that carries no `owner:` field at all - triggers, entities, decisions, " +
+ "obligations, telemetry ledgers - so there is no ownership claim on disk to enforce.",
+ aggregateOnly:
+ "reports counts, rates and verdicts over the vault with no per-artifact identity in the " +
+ "payload; a hidden page contributes to a number the caller cannot decompose.",
+ ownerFiltered:
+ "reaches owner-taggable artifacts and is filtered through the ownership rule before it " +
+ "answers (a-label-is-not-a-boundary, U3); the probe below is what holds that true.",
+ configuredCorpus:
+ "operates on an operator-configured corpus outside `Brain/` - a dataset file, a source " +
+ "directory, a codegraph index - which carries no page frontmatter to own.",
+ signalCluster:
+ "reads the pre-dream review over INBOX SIGNAL clusters. A signal carries no `owner:` " +
+ "anywhere in this product, so every row here - a topic, a decision, a count - is a fold " +
+ "over shared artifacts and names no owner-private page.",
+ recompileLane:
+ "plans a recompile of DERIVED pages whose sources moved (`Brain/sources`, `Brain/reports`). " +
+ "The fixture holds no derived page, so this recipe reaches no owner-taggable content; the " +
+ "gap is recorded rather than papered over with a recipe that cannot fail.",
+ signalAuthorship:
+ "groups SIGNALS by the `agent:` that wrote them. A signal carries no `owner:` anywhere in " +
+ "this product, so the agent column names the author of a SHARED artifact - the same fact " +
+ "`brain_agent_query`'s roster publishes by design - and never an owner-private page.",
+});
+
+/**
+ * The one reason that claims a call REACHES owner-bearing content.
+ *
+ * Named as a set rather than compared inline so the differential's
+ * exemption is an explicit list of classifications, not a silence: every
+ * other reason in {@link REASON} asserts unreachability, and the probe
+ * holds it to that.
+ */
+export const REASONS_REACHING_OWNER_CONTENT: ReadonlySet<string> = new Set([REASON.ownerFiltered]);
+
+/**
+ * Measured shape of the probe, quoted in `docs/architecture.md`,
+ * `docs/mcp.md` and the release notes. Equalities, not floors - see the
+ * test that reads them.
+ */
+export const PROBE_ENTRY_COUNT = 99;
+export const PROBE_RECIPE_COUNT = 226;
+export const PROBE_TWO_SIDED_COUNT = 32;
+
+/**
+ * `brain_trigger` read arguments, with the queue populated first.
+ *
+ * `list` and `history` read what a PRIOR scan persisted, so against an
+ * empty queue their isolation claim is untestable - the "clean sweep
+ * over an empty fixture" this file exists to prevent. The scan is done
+ * HERE rather than in {@link seedTwoOwnerFixture} because a populated
+ * queue suppresses `brain_idea_discovery`: idea discovery skips
+ * candidates already queued, so seeding globally would silently empty
+ * that probe instead.
+ *
+ * `terminal` dismisses what the scan created, because `history` reports
+ * only terminal records and `list` reports only non-terminal ones - one
+ * queue state cannot exercise both. Each recipe gets its own vault, so
+ * the two states never collide.
+ */
+export function triggerQueueArgs(
+ operation: string,
+ terminal = false,
+): (vault: string) => Record<string, unknown> {
+ return (vault: string) => {
+ const now = new Date();
+ const scan = scanTriggers(vault, { now });
+ if (terminal) {
+ for (const record of scan.created) transitionTrigger(vault, record.id, "dismiss", { now });
+ }
+ return { operation };
+ };
+}
+
+/**
+ * `brain_hygiene mode=apply` arguments, derived from a live scan.
+ *
+ * A finding id is `sha256(targets.sorted().join("\0")).slice(0, 12)`
+ * (`hygiene/detectors/id.ts`) - derivable rather than secret, which is
+ * why withholding it from the scan was never the boundary. A LITERAL id
+ * in the recipe would select nothing and the probe would go green over
+ * an apply that did nothing, which is exactly how this mode shipped
+ * planning against the unfiltered report.
+ */
+export function hygieneApplyArgs(vault: string): Record<string, unknown> {
+ return {
+ mode: "apply",
+ ids: runHygieneScan(vault, { now: new Date() }).findings.map((f) => f.id),
+ };
+}
+
+/**
+ * Tools that return vault content but are NOT owner-scoped after this
+ * wave. Listed with a reason so the gap is recorded rather than
+ * forgotten β€” this is the honest half of the matrix.
+ */
+export const UNSCOPED_CONTENT: ReadonlyArray<ProbeEntry> = [
+ { name: "brain_session_grep", calls: one({ query: QUERY }, REASON.sessionLane) },
+ { name: "brain_session_expand", calls: one({ id: "sess-probe:0" }, REASON.sessionLane) },
+ {
+ name: "brain_session_summary",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.sessionLane },
+ { args: { operation: "get", session_id: "sess-probe" }, reason: REASON.sessionLane },
+ {
+ args: { operation: "write", session_id: "sess-probe", request: "probe digest" },
+ reason: REASON.sessionLane,
+ },
+ ],
+ },
+ {
+ name: "brain_session_describe",
+ calls: one({ session_id: "sess-probe" }, REASON.sessionLane),
+ },
+ {
+ name: "brain_note_history",
+ calls: one(
+ { path: "notes/shared.md" },
+ "git commit metadata (subjects, authors, dates) for a path the caller already names, " +
+ "read from the repository rather than from page frontmatter. Every response shape it " +
+ "can produce - no repo, no commits, N phases - is distinguishable from a refusal, so a " +
+ "filter here would announce the existence of the page it is meant to hide while the " +
+ "same history stays readable through git itself.",
+ ),
+ },
+ {
+ name: "brain_artifact_get",
+ calls: one(
+ { artifact_id: "art-never-issued" },
+ "replays, by opaque id, a payload this process already returned to this caller - and " +
+ "already filtered under whatever scope produced it. The stored envelope keeps no page " +
+ "identity, so there is nothing left to re-apply the ownership rule to.",
+ ),
+ },
+ {
+ name: "brain_pre_compact_extract",
+ calls: one(
+ { session_id: "sess-probe", turn_start: 1, turn_end: 2, text: QUERY },
+ "extracts from caller-supplied text, not the vault: every byte of the response is " +
+ "derived from the `text` argument the caller passed in.",
+ ),
+ },
+ {
+ name: "brain_recall_gate",
+ calls: one(
+ { prompt: QUERY },
+ "a verdict over a caller-supplied question - recall/skip and why - with no artifact " +
+ "identity and no body prose in the payload.",
+ ),
+ },
+];
+
+/**
+ * Everything else: metadata, analytics, maintenance, writers, catalog.
+ *
+ * A tool with several modes, views or operations carries one recipe per
+ * mode, view or operation. One executed view is not an executed
+ * classification, and the two leaks this file missed - `brain_hygiene
+ * mode=apply` writing across the boundary, and three of
+ * `brain_analytics`' five views returning another owner's prose - were
+ * both hidden behind a single green recipe for a sibling mode.
+ */
+export const NON_CONTENT: ReadonlyArray<ProbeEntry> = [
+ { name: "brain_agenda", calls: one({ events: [] }, REASON.writerEcho) },
+ {
+ name: "brain_agent_diff",
+ calls: [
+ { args: { mode: "browse" }, reason: REASON.ownerFiltered },
+ { args: { mode: "search", query: CROSS_OWNER_MARKER }, reason: REASON.ownerFiltered },
+ { args: { mode: "diff" }, reason: REASON.ownerFiltered },
+ { args: { mode: "map" }, reason: REASON.ownerFiltered },
+ ],
+ },
+ {
+ name: "brain_analytics",
+ calls: [
+ { args: { view: "timeline" }, reason: REASON.ownerFiltered },
+ { args: { view: "attention_flows", operation: "list" }, reason: REASON.ownerlessLane },
+ // The topic is the SHARED one on purpose. A marker-bearing topic
+ // would be the caller's own argument echoed back, which is not a
+ // disclosure; the fixture instead gives an owner-A preference that
+ // shared topic, so the fan-out from one topic to every preference
+ // carrying it is what the probe measures.
+ { args: { view: "belief_evolution", topic: SHARED_TOPIC }, reason: REASON.ownerFiltered },
+ {
+ args: { view: "concept_synthesis", id: SHARED_ID, include_unlinked: true },
+ reason: REASON.ownerFiltered,
+ },
+ { args: { view: "dedup" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_append_note",
+ calls: one({ path: "notes/shared.md", content: "probe append" }, REASON.writerEcho),
+ },
+ {
+ name: "brain_apply_evidence",
+ calls: one(
+ { pref_id: "pref-shared", artifact: "[[notes/shared.md]]", result: "applied" },
+ REASON.writerEcho,
+ ),
+ },
+ { name: "brain_audit", calls: one({ pref_id: "pref-shared" }, REASON.callerNamedArtifact) },
+ { name: "brain_backlinks", calls: one({ id: SHARED_ID }, REASON.ownerFiltered) },
+ {
+ name: "brain_benchmark",
+ calls: one(
+ { operation: "run", dataset: "datasets/probe-absent.jsonl" },
+ REASON.configuredCorpus,
+ ),
+ },
+ {
+ name: "brain_bridges",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "discover" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "accept", source: "notes/shared.md", target: "notes/owned-a.md" },
+ reason: REASON.ownerlessLane,
+ },
+ {
+ args: { operation: "dismiss", source: "notes/shared.md", target: "notes/owned-a.md" },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_claims",
+ calls: [
+ { args: { operation: "current" }, reason: REASON.ownerFiltered },
+ { args: { operation: "at", at: LOG_EVENT_DATE }, reason: REASON.ownerFiltered },
+ { args: { operation: "history" }, reason: REASON.ownerFiltered },
+ { args: { operation: "replaced", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
+ { args: { operation: "contests", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
+ { args: { operation: "rebuild" }, reason: REASON.aggregateOnly },
+ ],
+ },
+ {
+ name: "brain_clusters",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.aggregateOnly },
+ { args: { operation: "run" }, reason: REASON.ownerFiltered },
+ ],
+ },
+ { name: "brain_codegraph_report", calls: one({}, REASON.configuredCorpus) },
+ {
+ name: "brain_context_pack_outcome",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "summary" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "post", sample_id: "probe-sample", first_pass_success: true },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_context_presets",
+ calls: [
+ { args: { operation: "show" }, reason: REASON.catalog },
+ { args: { operation: "suggest" }, reason: REASON.catalog },
+ { args: { operation: "diff" }, reason: REASON.catalog },
+ ],
+ },
+ {
+ name: "brain_context_receipts",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "summary" }, reason: REASON.ownerlessLane },
+ { args: { operation: "show", id: "rcpt-probe-absent" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_create_note",
+ calls: one({ path: "notes/probe-created.md" }, REASON.writerEcho),
+ },
+ {
+ name: "brain_dead_ends",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "record", approach: "probe approach", reason: "probe reason" },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_decision",
+ calls: [
+ { args: { action: "list" }, reason: REASON.ownerlessLane },
+ { args: { action: "show", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "history" }, reason: REASON.ownerlessLane },
+ { args: { action: "recall" }, reason: REASON.ownerlessLane },
+ { args: { action: "similar", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "compare", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "outcome", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "rate", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "record", title: "probe decision" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_delete_by_source",
+ calls: one({ source_file: "sources/paper.md" }, REASON.writerEcho),
+ },
+ {
+ name: "brain_derive_fact",
+ calls: one(
+ {
+ slug: "probe-derived",
+ topic: "probe",
+ principle: "probe derived principle",
+ premises: [`[[${SHARED_ID}]]`],
+ level: "deduced",
+ },
+ REASON.writerEcho,
+ ),
+ },
+ {
+ name: "brain_design_note",
+ calls: [
+ // The grounding stores carry no `owner:`, but the plan envelope's
+ // `link_candidates` names Brain artifact ids - so this recipe DOES
+ // reach owner-taggable content and is filtered, rather than being
+ // unable to name it.
+ { args: { topic: "probe topic" }, reason: REASON.ownerFiltered },
+ {
+ args: {
+ topic: "probe topic",
+ note: {
+ title: "Probe",
+ alternatives: [
+ {
+ name: "only",
+ approach: "probe approach",
+ tradeoffs: "probe tradeoffs",
+ recommended: true,
+ },
+ ],
+ },
+ },
+ reason: REASON.writerEcho,
+ label: "commit",
+ },
+ ],
+ },
+ { name: "brain_diarize", calls: one({ entity: "probe-entity" }, REASON.ownerlessLane) },
+ {
+ name: "brain_distill_source",
+ calls: one({ source_path: "sources/paper.md", claims: ["probe claim"] }, REASON.writerEcho),
+ },
+ {
+ name: "brain_doctor",
+ calls: [
+ { args: {}, reason: REASON.ownerFiltered },
+ { args: { strict: true }, reason: REASON.ownerFiltered },
+ { args: { repair: true }, reason: REASON.ownerFiltered },
+ ],
+ },
+ {
+ name: "brain_dream",
+ calls: [
+ { args: { action: "list" }, reason: REASON.aggregateOnly },
+ { args: { action: "run", dry_run: true }, reason: REASON.ownerFiltered },
+ { args: { action: "stage" }, reason: REASON.ownerFiltered },
+ { args: { action: "validate", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
+ { args: { action: "apply", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
+ { args: { action: "discard", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
+ { args: { action: "retriage", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
+ ],
+ },
+ {
+ name: "brain_entity",
+ calls: [
+ { args: { view: "list" }, reason: REASON.ownerlessLane },
+ { args: { view: "get", query: "probe-entity" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_eval",
+ calls: one({ dataset: "datasets/probe-absent.jsonl" }, REASON.configuredCorpus),
+ },
+ { name: "brain_event_trace", calls: one({ date: LOG_EVENT_DATE }, REASON.ownerFiltered) },
+ {
+ name: "brain_expire",
+ calls: one(
+ { id: `sig-2026-05-01-${NEUTRAL_SIGNAL_SLUG}`, expires: "2030-01-01" },
+ REASON.callerNamedArtifact,
+ ),
+ },
+ {
+ name: "brain_extract_signals",
+ calls: [
+ { args: { session: "sess-probe" }, reason: REASON.sessionLane },
+ {
+ args: {
+ session: "sess-probe",
+ items: [
+ {
+ topic: "probe",
+ signal: "positive",
+ principle: "probe principle",
+ confidence: 0.9,
+ },
+ ],
+ },
+ reason: REASON.writerEcho,
+ label: "commit",
+ },
+ ],
+ },
+ {
+ name: "brain_feedback",
+ calls: one(
+ { topic: "probe", signal: "positive", principle: "probe principle" },
+ REASON.writerEcho,
+ ),
+ },
+ { name: "brain_foresight", calls: one({}, REASON.aggregateOnly) },
+ {
+ name: "brain_generation_reports",
+ calls: [
+ { args: { action: "list" }, reason: REASON.ownerlessLane },
+ { args: { action: "summary" }, reason: REASON.ownerlessLane },
+ {
+ args: {
+ action: "record",
+ handoff_kind: "context_pack",
+ ref: "probe-ref",
+ agent: OWNER_B,
+ prompt: "probe prompt",
+ enable: true,
+ },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ { name: "brain_health", calls: one({}, REASON.ownerFiltered) },
+ {
+ name: "brain_hygiene",
+ calls: [
+ { args: { mode: "scan" }, reason: REASON.ownerFiltered },
+ { args: { mode: "refresh", dry_run: true }, reason: REASON.recompileLane },
+ // The ids come from a LIVE scan of the seeded fixture. A literal
+ // id here would select nothing, and a recipe that selects nothing
+ // is how `apply` kept a green probe while planning against the
+ // unfiltered report and retiring another owner's preference.
+ { args: hygieneApplyArgs, label: "mode=apply", reason: REASON.ownerFiltered },
+ ],
+ },
+ { name: "brain_idea_discovery", calls: one({}, REASON.ownerFiltered) },
+ { name: "brain_idea_lineage", calls: one({ id: SHARED_ID }, REASON.callerNamedArtifact) },
+ {
+ name: "brain_ingest_batch_plan",
+ calls: one({ source_dir: "sources" }, REASON.configuredCorpus),
+ },
+ {
+ name: "brain_ingest_source",
+ calls: one(
+ { source_path: "sources/paper.md", summary: "probe summary", entities: [] },
+ REASON.writerEcho,
+ ),
+ },
+ {
+ name: "brain_intake_entities",
+ calls: one({ entities: [], source: "sources/paper.md" }, REASON.writerEcho),
+ },
+ { name: "brain_intent_review", calls: one({}, REASON.signalCluster) },
+ {
+ name: "brain_intention",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "show" }, reason: REASON.ownerlessLane },
+ { args: { operation: "set", text: "probe intention" }, reason: REASON.ownerlessLane },
+ { args: { operation: "move", scope: "probe-scope" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ { name: "brain_knowledge_gaps", calls: one({}, REASON.aggregateOnly) },
+ {
+ name: "brain_labels",
+ calls: [
+ { args: { operation: "show", path: "notes/shared.md" }, reason: REASON.callerNamedArtifact },
+ {
+ args: {
+ operation: "assign",
+ path: "notes/shared.md",
+ dimension: "probe",
+ value: "probe",
+ },
+ reason: REASON.callerNamedArtifact,
+ },
+ {
+ args: { operation: "remove", path: "notes/shared.md", dimension: "probe" },
+ reason: REASON.callerNamedArtifact,
+ },
+ ],
+ },
+ {
+ name: "brain_lifecycle",
+ calls: [
+ { args: { action: "curator" }, reason: REASON.aggregateOnly },
+ { args: { action: "tip", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
+ {
+ args: { action: "tombstone", path: "notes/shared.md", reason: "probe" },
+ reason: REASON.writerEcho,
+ },
+ {
+ args: {
+ action: "supersede",
+ predecessor: "notes/shared.md",
+ successor: `[[${SHARED_ID}]]`,
+ reason: "probe",
+ },
+ reason: REASON.writerEcho,
+ },
+ {
+ args: {
+ action: "temporal-replace",
+ predecessor: "notes/shared.md",
+ successor: "notes/renamed.md",
+ at: LOG_EVENT_DATE,
+ },
+ reason: REASON.writerEcho,
+ },
+ ],
+ },
+ {
+ name: "brain_maintenance",
+ calls: [
+ { args: { operation: "status" }, reason: REASON.aggregateOnly },
+ { args: { operation: "run", force: true }, reason: REASON.aggregateOnly },
+ ],
+ },
+ { name: "brain_mcp_landscape", calls: one({}, REASON.catalog) },
+ {
+ name: "brain_memory_bridge",
+ calls: [
+ { args: {}, reason: REASON.writerEcho },
+ {
+ args: { action: "add", target: "memory", content: "probe memory" },
+ reason: REASON.writerEcho,
+ },
+ {
+ args: { action: "replace", target: "memory", content: "probe memory" },
+ reason: REASON.writerEcho,
+ },
+ ],
+ },
+ { name: "brain_moc_audit", calls: one({ id: HUB_ID }, REASON.ownerFiltered) },
+ { name: "brain_note", calls: one({ text: "probe note" }, REASON.writerEcho) },
+ {
+ name: "brain_note_lifecycle",
+ calls: [
+ {
+ args: { action: "rename", path: "notes/shared.md", to: "notes/renamed.md" },
+ reason: REASON.writerEcho,
+ },
+ {
+ args: { action: "move", path: "notes/shared.md", to: "notes/moved.md" },
+ reason: REASON.writerEcho,
+ },
+ { args: { action: "archive", path: "notes/shared.md" }, reason: REASON.writerEcho },
+ { args: { action: "delete", path: "notes/shared.md" }, reason: REASON.writerEcho },
+ ],
+ },
+ {
+ name: "brain_obligation",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "show", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "add", title: "probe obligation", cadence: "weekly" },
+ reason: REASON.ownerlessLane,
+ },
+ { args: { operation: "done", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
+ { args: { operation: "remove", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ { name: "brain_observed_use", calls: one({ entries: [] }, REASON.writerEcho) },
+ {
+ name: "brain_pinned_context",
+ calls: [
+ { args: { operation: "read" }, reason: REASON.ownerlessLane },
+ { args: { operation: "write", content: "probe pinned" }, reason: REASON.ownerlessLane },
+ { args: { operation: "append", content: "probe pinned" }, reason: REASON.ownerlessLane },
+ { args: { operation: "clear" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_procedural_graph",
+ calls: [
+ { args: { operation: "show" }, reason: REASON.ownerlessLane },
+ { args: { operation: "rebuild" }, reason: REASON.ownerlessLane },
+ { args: { operation: "hints" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_procedural_memory",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "reconcile" }, reason: REASON.ownerlessLane },
+ { args: { operation: "mark_used", id: "proc-probe-absent" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "mark_outcome", id: "proc-probe-absent", outcome: "success" },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_recall_feedback",
+ calls: one({ query: QUERY, result_path: "notes/shared.md", verdict: "up" }, REASON.writerEcho),
+ },
+ {
+ name: "brain_recall_telemetry",
+ calls: [
+ { args: { operation: "summary" }, reason: REASON.ownerlessLane },
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "gate_list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "gate_summary" }, reason: REASON.ownerlessLane },
+ { args: { operation: "observed_reuse" }, reason: REASON.ownerlessLane },
+ { args: { operation: "cost" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_recurrence",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "show", content_hash: "probe-hash" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "learn", content_hash: "probe-hash", scope: "probe" },
+ reason: REASON.ownerlessLane,
+ },
+ {
+ args: { operation: "forget", content_hash: "probe-hash", scope: "probe" },
+ reason: REASON.ownerlessLane,
+ },
+ { args: { operation: "purge_source", source_id: "probe" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_research_report",
+ calls: one(
+ { title: "probe report", sources: ["sources/paper.md"], findings: ["probe finding"] },
+ REASON.writerEcho,
+ ),
+ },
+ { name: "brain_retention", calls: one({}, REASON.ownerFiltered) },
+ { name: "brain_review_candidates", calls: one({}, REASON.ownerFiltered) },
+ {
+ name: "brain_route_metrics",
+ calls: [
+ { args: { operation: "summary" }, reason: REASON.ownerlessLane },
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_scaffold_stub",
+ calls: [
+ { args: { action: "list" }, reason: REASON.ownerFiltered },
+ // A neutral target: naming the marker here would be the caller's
+ // own argument echoed back by the writer, not a disclosure.
+ { args: { action: "write", target: "Projects/ProbeStub" }, reason: REASON.writerEcho },
+ ],
+ },
+ {
+ name: "brain_secrets",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "run", name: "probe-secret", command: ["true"] },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_session_checkpoint",
+ calls: one({ session_id: "sess-probe" }, REASON.writerEcho),
+ },
+ {
+ name: "brain_skill_proposals",
+ calls: [
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ { args: { operation: "learn" }, reason: REASON.ownerlessLane },
+ { args: { operation: "usage" }, reason: REASON.ownerlessLane },
+ { args: { operation: "recover" }, reason: REASON.ownerlessLane },
+ { args: { operation: "evidence", slug: "probe-proposal" }, reason: REASON.ownerlessLane },
+ { args: { operation: "accept", slug: "probe-proposal" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "reject", slug: "probe-proposal", note: "probe" },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ { name: "brain_sources", calls: one({}, REASON.signalAuthorship) },
+ { name: "brain_stale_scan", calls: one({}, REASON.ownerFiltered) },
+ { name: "brain_status", calls: one({}, REASON.aggregateOnly) },
+ { name: "brain_switch_vault", calls: one({ name: "probe-profile" }, REASON.writerEcho) },
+ {
+ name: "brain_tension",
+ calls: [
+ { args: { action: "list" }, reason: REASON.ownerlessLane },
+ { args: { action: "detect" }, reason: REASON.ownerlessLane },
+ { args: { action: "show", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "confirm", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "dismiss", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { action: "resolve", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_tiers",
+ calls: [
+ { args: { operation: "check" }, reason: REASON.aggregateOnly },
+ { args: { operation: "restore", path: "notes/shared.md" }, reason: REASON.aggregateOnly },
+ { args: { operation: "accept", path: "notes/shared.md" }, reason: REASON.aggregateOnly },
+ ],
+ },
+ {
+ name: "brain_token_impact",
+ calls: [
+ { args: { operation: "summary" }, reason: REASON.ownerlessLane },
+ { args: { operation: "list" }, reason: REASON.ownerlessLane },
+ {
+ args: { operation: "record", baseline_tokens: 100, packed_tokens: 50 },
+ reason: REASON.ownerlessLane,
+ },
+ { args: { operation: "outcome", outcome: "first_pass" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_trigger",
+ calls: [
+ { args: triggerQueueArgs("list"), label: "operation=list", reason: REASON.ownerFiltered },
+ { args: { operation: "scan" }, reason: REASON.ownerFiltered },
+ {
+ args: triggerQueueArgs("history", true),
+ label: "operation=history",
+ reason: REASON.ownerFiltered,
+ },
+ { args: { operation: "acknowledge", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { operation: "dismiss", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { operation: "act", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { operation: "suppress", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { operation: "unsuppress", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ {
+ name: "brain_truth",
+ calls: [
+ { args: { operation: "slots" }, reason: REASON.ownerlessLane },
+ { args: { operation: "conflicts" }, reason: REASON.ownerlessLane },
+ { args: { operation: "collisions" }, reason: REASON.ownerlessLane },
+ { args: { operation: "aggregate" }, reason: REASON.ownerlessLane },
+ {
+ args: {
+ operation: "ingest",
+ entity: "probe-entity",
+ aspect: "probe-aspect",
+ value: "probe",
+ source: "[[notes/shared.md]]",
+ },
+ reason: REASON.ownerlessLane,
+ },
+ ],
+ },
+ {
+ name: "brain_tune",
+ calls: [
+ { args: { operation: "status" }, reason: REASON.aggregateOnly },
+ { args: { operation: "reset" }, reason: REASON.aggregateOnly },
+ { args: { operation: "run" }, reason: REASON.aggregateOnly },
+ ],
+ },
+ { name: "brain_unlinked_mentions", calls: one({ id: SHARED_ID }, REASON.ownerFiltered) },
+ {
+ name: "brain_update_note",
+ calls: one({ path: "notes/shared.md", content: "probe update" }, REASON.writerEcho),
+ },
+ { name: "brain_watchdog", calls: one({}, REASON.aggregateOnly) },
+ { name: "brain_write_batch", calls: one({ operations: [] }, REASON.writerEcho) },
+ {
+ name: "brain_write_session",
+ calls: [
+ { args: { op: "list" }, reason: REASON.ownerlessLane },
+ { args: { op: "status", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { op: "open", target: "Brain/probe-session.md" }, reason: REASON.ownerlessLane },
+ {
+ args: { op: "submit", session_id: "ws-probe-absent", text: "probe text" },
+ reason: REASON.ownerlessLane,
+ },
+ { args: { op: "approve", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
+ { args: { op: "abandon", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
+ ],
+ },
+ { name: "get_skill", calls: one({ name: "open-second-brain" }, REASON.catalog) },
+ { name: "list_skills", calls: one({}, REASON.catalog) },
+ { name: "schema_apply_mutations", calls: one({ mutations: [] }, REASON.writerEcho) },
+ {
+ name: "schema_inspect",
+ calls: [
+ { args: { view: "stats" }, reason: REASON.aggregateOnly },
+ { args: { view: "graph" }, reason: REASON.aggregateOnly },
+ { args: { view: "lint" }, reason: REASON.aggregateOnly },
+ { args: { view: "orphans" }, reason: REASON.aggregateOnly },
+ { args: { view: "packs" }, reason: REASON.catalog },
+ { args: { view: "active_pack" }, reason: REASON.catalog },
+ { args: { view: "explain_type", type: "brain-preference" }, reason: REASON.catalog },
+ ],
+ },
+ { name: "second_brain_capabilities", calls: one({}, REASON.catalog) },
+ { name: "second_brain_status", calls: one({}, REASON.aggregateOnly) },
+ { name: "skills_attach", calls: one({ query: QUERY }, REASON.catalog) },
+ { name: "tool_hydrate", calls: one({}, REASON.catalog) },
+ { name: "vault_health", calls: one({}, REASON.aggregateOnly) },
+];
+
+/**
+ * Every entry the isolation probe drives, checked at module load.
+ *
+ * Both unasserted buckets, in one list: `SCOPED_SURFACES` is excluded
+ * because its members are already driven, per surface, by the fifteen
+ * behavioural tests below.
+ */
+export const PROBE_ENTRIES: ReadonlyArray<ProbeEntry> = [
+ ...UNSCOPED_CONTENT.map((e) => assertProbeEntry("UNSCOPED_CONTENT", e)),
+ ...NON_CONTENT.map((e) => assertProbeEntry("NON_CONTENT", e)),
+];
+
+/**
+ * A recipe's test name: the tool plus whatever selects the code path.
+ *
+ * Read off the recipe rather than hand-written, so a recipe added later
+ * cannot be the one with a name that no longer matches its arguments.
+ */
+export const DISPATCH_KEYS = ["mode", "view", "operation", "action", "op"] as const;
+
+export function probeLabel(name: string, recipe: ProbeCall, index: number): string {
+ if (recipe.label !== undefined) return `${name} ${recipe.label}`;
+ if (typeof recipe.args === "function") return `${name} #${index}`;
+ for (const key of DISPATCH_KEYS) {
+ const value = recipe.args[key];
+ if (typeof value === "string") return `${name} ${key}=${value}`;
+ }
+ return index === 0 ? name : `${name} #${index}`;
+}
diff --git a/tests/mcp/agent-scope-matrix.test.ts b/tests/mcp/agent-scope-matrix.test.ts
index 2b19921d..33373eb6 100644
--- a/tests/mcp/agent-scope-matrix.test.ts
+++ b/tests/mcp/agent-scope-matrix.test.ts
@@ -55,8 +55,6 @@ import { regenerateActive } from "../../src/core/brain/active.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { runHygieneScan } from "../../src/core/brain/hygiene/scan.ts";
-import { scanTriggers } from "../../src/core/brain/triggers/scan.ts";
-import { transitionTrigger } from "../../src/core/brain/triggers/store.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import {
BRAIN_CONFIDENCE,
@@ -64,6 +62,32 @@ import {
BRAIN_PREFERENCE_STATUS,
} from "../../src/core/brain/types.ts";
import { OWNER_SCOPE_REFUSAL } from "../../src/mcp/owner-scope-refusal.ts";
+import {
+ CROSS_OWNER_MARKER,
+ HUB_ID,
+ LOG_EVENT_DATE,
+ NEUTRAL_SIGNAL_SLUG,
+ OWNER_A,
+ OWNER_B,
+ PROBE,
+ PROBE_ENTRIES,
+ PROBE_ENTRY_COUNT,
+ PROBE_RECIPE_COUNT,
+ PROBE_TERMS,
+ PROBE_TWO_SIDED_COUNT,
+ QUERY,
+ REASON,
+ REASONS_REACHING_OWNER_CONTENT,
+ SCOPE_SOURCE,
+ SCOPED_SURFACES,
+ SHARED_ID,
+ SHARED_TITLE,
+ SHARED_TOPIC,
+ REASON_MIN_CHARS,
+ assertProbeEntry,
+ probeLabel,
+ type ProbeCall,
+} from "../helpers/tool-probe-catalogue.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import type { ServerContext, ToolDefinition } from "../../src/mcp/tool-contract.ts";
@@ -80,1036 +104,6 @@ import type { ServerContext, ToolDefinition } from "../../src/mcp/tool-contract.
*/
process.env["HOME"] = mkdtempSync(join(tmpdir(), "o2b-scope-matrix-home-"));
-const OWNER_A = "agent-a";
-const OWNER_B = "agent-b";
-const QUERY = "lattice widgets";
-/** Probe path whose derived query terms appear verbatim in every note. */
-const PROBE = "lattice.md";
-const PROBE_TERMS = `${PROBE} lattice`;
-
-/**
- * The string the isolation probe hunts for.
- *
- * It appears ONLY inside artifacts owned by {@link OWNER_A} - in their
- * ids, their paths, their topics, their titles and their body prose - so
- * one `not.toContain` catches every channel a surface might use to name
- * one of them, without the probe having to know which field carried it.
- */
-const CROSS_OWNER_MARKER = "secretmarkerzz";
-
-/** The UTC day the fixture's log event lands on; `brain_event_trace` selects by date. */
-const LOG_EVENT_DATE = "2026-05-04";
-
-/** Shared hub the fixture's MOC audit is driven against. */
-const HUB_ID = "pref-hub";
-/** Shared preference every owner-A artifact references, and the probe's link target. */
-const SHARED_ID = "pref-shared";
-/** Title of {@link SHARED_ID}; the term `brain_unlinked_mentions` matches on. */
-const SHARED_TITLE = "Shared Pref";
-/**
- * Topic of {@link SHARED_ID}, and deliberately ALSO the topic of one
- * owner-A preference.
- *
- * A `topic:` argument is a fan-out: `buildBeliefEvolution` resolves it to
- * every `pref-`/`ret-` page carrying that topic, so a caller naming a
- * topic it is entitled to still reaches preferences it is not. Probing
- * that with a marker-bearing topic would prove nothing - the marker
- * would be the caller's own argument echoed back.
- */
-const SHARED_TOPIC = "shared";
-/** Slug of the ownerless signal that evidences the owner-A preference. */
-const NEUTRAL_SIGNAL_SLUG = "neutral-probe-signal";
-
-/** How a surface learns which agent is asking. */
-const SCOPE_SOURCE = Object.freeze({
- /** An explicit `agent_scope` input argument. */
- argument: "argument",
- /** `ServerContext.agentName`, for a surface that takes no arguments. */
- serverIdentity: "server-identity",
-} as const);
-
-type ScopeSource = (typeof SCOPE_SOURCE)[keyof typeof SCOPE_SOURCE];
-
-interface ScopedSurface {
- readonly name: string;
- readonly source: ScopeSource;
- /**
- * True when isolation is behind `integrity.owner_scope_delivery`.
- * Preference-backed surfaces are gated (their scope may be defaulted
- * from the server identity, which would narrow a vault that never
- * opted in). Search-backed surfaces are not: their scope only ever
- * arrives as an explicit per-call argument, so honouring it cannot
- * narrow anything the caller did not ask to narrow.
- */
- readonly gated: boolean;
-}
-
-/** Content-returning tools that consult the ownership rule. */
-const SCOPED_SURFACES: ReadonlyArray<ScopedSurface> = [
- { name: "brain_context", source: SCOPE_SOURCE.serverIdentity, gated: true },
- { name: "brain_context_pack", source: SCOPE_SOURCE.argument, gated: true },
- { name: "brain_pre_compress_pack", source: SCOPE_SOURCE.argument, gated: true },
- { name: "brain_anticipatory_context", source: SCOPE_SOURCE.argument, gated: true },
- { name: "brain_brief", source: SCOPE_SOURCE.argument, gated: true },
- { name: "brain_retrieval_plan", source: SCOPE_SOURCE.argument, gated: true },
- { name: "brain_query", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_search", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_search_expand", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_file_context", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_deep_synthesis", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_search_by_source", source: SCOPE_SOURCE.argument, gated: false },
- { name: "second_brain_query", source: SCOPE_SOURCE.argument, gated: false },
- { name: "brain_agent_query", source: SCOPE_SOURCE.argument, gated: false },
-];
-
-/**
- * One probe recipe: the arguments that DRIVE one mode / view / operation
- * of a tool against the two-owner fixture, and a written reason for the
- * classification THAT CALL carries.
- *
- * The reason lives on the call rather than on the tool because a tool is
- * not one classification. `brain_analytics view=concept_synthesis`
- * reaches another owner's body prose and `view=dedup` reaches an ingest
- * counter; one entry claiming one reason for both is the same
- * unexecuted label this file exists to remove, and it is how
- * `concept_synthesis` shipped unfiltered behind a green `view=timeline`.
- */
-interface ProbeCall {
- /**
- * Arguments the isolation probe calls the tool with, or a function of
- * the vault that computes them after the fixture is seeded.
- *
- * `{}` only where the tool's input schema declares no property the
- * probe needs, never as a stand-in for "I did not work out what
- * drives this one". The function form exists for the one recipe whose
- * arguments are derived from vault state - `brain_hygiene mode=apply`
- * selects findings by id, and a static id would drive a call that
- * matches nothing.
- */
- readonly args: Record<string, unknown> | ((vault: string) => Record<string, unknown>);
- /** Why THIS call sits in the bucket it sits in. */
- readonly reason: string;
- /**
- * Test-name suffix for a recipe whose arguments are computed, where
- * the dispatch key cannot be read off a literal record.
- */
- readonly label?: string;
-}
-
-/** One tool, and every call recipe the probe drives it with. */
-interface ProbeEntry {
- readonly name: string;
- readonly calls: ReadonlyArray<ProbeCall>;
-}
-
-/** A single-recipe entry, spelled without the array ceremony. */
-function one(args: ProbeCall["args"], reason: string): ReadonlyArray<ProbeCall> {
- return [{ args, reason }];
-}
-
-/**
- * Shortest reason this file accepts. A one-word reason is the bare name
- * list with extra punctuation, so the floor is set above it.
- */
-const REASON_MIN_CHARS = 24;
-
-/**
- * Refuse an entry that carries no call recipes or no reason.
- *
- * `unknown` rather than {@link ProbeEntry}: the compiler already rejects
- * a bare name, and this is the second lock, for a `satisfies`-free cast
- * or a bucket built at runtime. It runs at module load over every entry,
- * so a nameless-args entry fails the whole file rather than one test.
- */
-function assertProbeEntry(bucket: string, entry: unknown): ProbeEntry {
- if (typeof entry !== "object" || entry === null) {
- throw new Error(`${bucket}: every entry must be a {name, calls} record`);
- }
- const row = entry as Partial<ProbeEntry>;
- if (typeof row.name !== "string" || row.name.length === 0) {
- throw new Error(`${bucket}: every entry must name a tool`);
- }
- if (!Array.isArray(row.calls) || row.calls.length === 0) {
- throw new Error(
- `${bucket}: ${row.name} has no 'calls'; a bucket entry the probe cannot call is a label`,
- );
- }
- for (const recipe of row.calls) {
- const shaped = recipe as Partial<ProbeCall>;
- const args = shaped.args;
- const argsOk =
- typeof args === "function" ||
- (typeof args === "object" && args !== null && !Array.isArray(args));
- if (!argsOk) {
- throw new Error(
- `${bucket}: ${row.name} has a call with no 'args'; a recipe the probe cannot call is a label`,
- );
- }
- if (typeof shaped.reason !== "string" || shaped.reason.trim().length < REASON_MIN_CHARS) {
- throw new Error(
- `${bucket}: ${row.name} needs a reason of at least ${REASON_MIN_CHARS} characters`,
- );
- }
- }
- return row as ProbeEntry;
-}
-
-/**
- * Reasons shared by more than one call, named once.
- *
- * The alternative - hundreds of hand-written sentences, most of them
- * saying the same thing in different words - is the natural-language
- * word list this repository forbids, and it would make two calls with
- * the same classification look like two different classifications.
- *
- * Each of these is a CLAIM the differential below executes. Every reason
- * except {@link REASON.ownerFiltered} asserts that the call cannot name
- * an owner-private artifact AT ALL, so the probe requires the marker to
- * be absent even with the gate OFF, where nothing is hidden. A call that
- * surfaces the marker unscoped has a false reason and fails here, which
- * is the difference between a classification and a label.
- */
-const REASON = Object.freeze({
- sessionLane:
- "session transcript lane: the records are keyed by session and turn, not by an " +
- "owner-taggable page, so `pageOwner` has no subject to read.",
- catalog:
- "a catalog of this server's own surface - the tool table, the skills manifest, the " +
- "preset list - answered without opening a vault page, so no page's owner is reachable.",
- writerEcho:
- "a writer: the response echoes the artifact this very call created, planned or refused, " +
- "so the only ownership it can name is the one the caller supplied.",
- callerNamedArtifact:
- "answers only about the artifact the caller already named, and every response shape it " +
- "can produce is distinguishable from a refusal - so a filter here would announce the " +
- "existence of the page it is meant to hide.",
- ownerlessLane:
- "reads a lane that carries no `owner:` field at all - triggers, entities, decisions, " +
- "obligations, telemetry ledgers - so there is no ownership claim on disk to enforce.",
- aggregateOnly:
- "reports counts, rates and verdicts over the vault with no per-artifact identity in the " +
- "payload; a hidden page contributes to a number the caller cannot decompose.",
- ownerFiltered:
- "reaches owner-taggable artifacts and is filtered through the ownership rule before it " +
- "answers (a-label-is-not-a-boundary, U3); the probe below is what holds that true.",
- configuredCorpus:
- "operates on an operator-configured corpus outside `Brain/` - a dataset file, a source " +
- "directory, a codegraph index - which carries no page frontmatter to own.",
- signalCluster:
- "reads the pre-dream review over INBOX SIGNAL clusters. A signal carries no `owner:` " +
- "anywhere in this product, so every row here - a topic, a decision, a count - is a fold " +
- "over shared artifacts and names no owner-private page.",
- recompileLane:
- "plans a recompile of DERIVED pages whose sources moved (`Brain/sources`, `Brain/reports`). " +
- "The fixture holds no derived page, so this recipe reaches no owner-taggable content; the " +
- "gap is recorded rather than papered over with a recipe that cannot fail.",
- signalAuthorship:
- "groups SIGNALS by the `agent:` that wrote them. A signal carries no `owner:` anywhere in " +
- "this product, so the agent column names the author of a SHARED artifact - the same fact " +
- "`brain_agent_query`'s roster publishes by design - and never an owner-private page.",
-});
-
-/**
- * The one reason that claims a call REACHES owner-bearing content.
- *
- * Named as a set rather than compared inline so the differential's
- * exemption is an explicit list of classifications, not a silence: every
- * other reason in {@link REASON} asserts unreachability, and the probe
- * holds it to that.
- */
-const REASONS_REACHING_OWNER_CONTENT: ReadonlySet<string> = new Set([REASON.ownerFiltered]);
-
-/**
- * Measured shape of the probe, quoted in `docs/architecture.md`,
- * `docs/mcp.md` and the release notes. Equalities, not floors - see the
- * test that reads them.
- */
-const PROBE_ENTRY_COUNT = 99;
-const PROBE_RECIPE_COUNT = 226;
-const PROBE_TWO_SIDED_COUNT = 32;
-
-/**
- * `brain_trigger` read arguments, with the queue populated first.
- *
- * `list` and `history` read what a PRIOR scan persisted, so against an
- * empty queue their isolation claim is untestable - the "clean sweep
- * over an empty fixture" this file exists to prevent. The scan is done
- * HERE rather than in {@link seedTwoOwnerFixture} because a populated
- * queue suppresses `brain_idea_discovery`: idea discovery skips
- * candidates already queued, so seeding globally would silently empty
- * that probe instead.
- *
- * `terminal` dismisses what the scan created, because `history` reports
- * only terminal records and `list` reports only non-terminal ones - one
- * queue state cannot exercise both. Each recipe gets its own vault, so
- * the two states never collide.
- */
-function triggerQueueArgs(
- operation: string,
- terminal = false,
-): (vault: string) => Record<string, unknown> {
- return (vault: string) => {
- const now = new Date();
- const scan = scanTriggers(vault, { now });
- if (terminal) {
- for (const record of scan.created) transitionTrigger(vault, record.id, "dismiss", { now });
- }
- return { operation };
- };
-}
-
-/**
- * `brain_hygiene mode=apply` arguments, derived from a live scan.
- *
- * A finding id is `sha256(targets.sorted().join("\0")).slice(0, 12)`
- * (`hygiene/detectors/id.ts`) - derivable rather than secret, which is
- * why withholding it from the scan was never the boundary. A LITERAL id
- * in the recipe would select nothing and the probe would go green over
- * an apply that did nothing, which is exactly how this mode shipped
- * planning against the unfiltered report.
- */
-function hygieneApplyArgs(vault: string): Record<string, unknown> {
- return {
- mode: "apply",
- ids: runHygieneScan(vault, { now: new Date() }).findings.map((f) => f.id),
- };
-}
-
-/**
- * Tools that return vault content but are NOT owner-scoped after this
- * wave. Listed with a reason so the gap is recorded rather than
- * forgotten β€” this is the honest half of the matrix.
- */
-const UNSCOPED_CONTENT: ReadonlyArray<ProbeEntry> = [
- { name: "brain_session_grep", calls: one({ query: QUERY }, REASON.sessionLane) },
- { name: "brain_session_expand", calls: one({ id: "sess-probe:0" }, REASON.sessionLane) },
- {
- name: "brain_session_summary",
- calls: [
- { args: { operation: "list" }, reason: REASON.sessionLane },
- { args: { operation: "get", session_id: "sess-probe" }, reason: REASON.sessionLane },
- {
- args: { operation: "write", session_id: "sess-probe", request: "probe digest" },
- reason: REASON.sessionLane,
- },
- ],
- },
- {
- name: "brain_session_describe",
- calls: one({ session_id: "sess-probe" }, REASON.sessionLane),
- },
- {
- name: "brain_note_history",
- calls: one(
- { path: "notes/shared.md" },
- "git commit metadata (subjects, authors, dates) for a path the caller already names, " +
- "read from the repository rather than from page frontmatter. Every response shape it " +
- "can produce - no repo, no commits, N phases - is distinguishable from a refusal, so a " +
- "filter here would announce the existence of the page it is meant to hide while the " +
- "same history stays readable through git itself.",
- ),
- },
- {
- name: "brain_artifact_get",
- calls: one(
- { artifact_id: "art-never-issued" },
- "replays, by opaque id, a payload this process already returned to this caller - and " +
- "already filtered under whatever scope produced it. The stored envelope keeps no page " +
- "identity, so there is nothing left to re-apply the ownership rule to.",
- ),
- },
- {
- name: "brain_pre_compact_extract",
- calls: one(
- { session_id: "sess-probe", turn_start: 1, turn_end: 2, text: QUERY },
- "extracts from caller-supplied text, not the vault: every byte of the response is " +
- "derived from the `text` argument the caller passed in.",
- ),
- },
- {
- name: "brain_recall_gate",
- calls: one(
- { prompt: QUERY },
- "a verdict over a caller-supplied question - recall/skip and why - with no artifact " +
- "identity and no body prose in the payload.",
- ),
- },
-];
-
-/**
- * Everything else: metadata, analytics, maintenance, writers, catalog.
- *
- * A tool with several modes, views or operations carries one recipe per
- * mode, view or operation. One executed view is not an executed
- * classification, and the two leaks this file missed - `brain_hygiene
- * mode=apply` writing across the boundary, and three of
- * `brain_analytics`' five views returning another owner's prose - were
- * both hidden behind a single green recipe for a sibling mode.
- */
-const NON_CONTENT: ReadonlyArray<ProbeEntry> = [
- { name: "brain_agenda", calls: one({ events: [] }, REASON.writerEcho) },
- {
- name: "brain_agent_diff",
- calls: [
- { args: { mode: "browse" }, reason: REASON.ownerFiltered },
- { args: { mode: "search", query: CROSS_OWNER_MARKER }, reason: REASON.ownerFiltered },
- { args: { mode: "diff" }, reason: REASON.ownerFiltered },
- { args: { mode: "map" }, reason: REASON.ownerFiltered },
- ],
- },
- {
- name: "brain_analytics",
- calls: [
- { args: { view: "timeline" }, reason: REASON.ownerFiltered },
- { args: { view: "attention_flows", operation: "list" }, reason: REASON.ownerlessLane },
- // The topic is the SHARED one on purpose. A marker-bearing topic
- // would be the caller's own argument echoed back, which is not a
- // disclosure; the fixture instead gives an owner-A preference that
- // shared topic, so the fan-out from one topic to every preference
- // carrying it is what the probe measures.
- { args: { view: "belief_evolution", topic: SHARED_TOPIC }, reason: REASON.ownerFiltered },
- {
- args: { view: "concept_synthesis", id: SHARED_ID, include_unlinked: true },
- reason: REASON.ownerFiltered,
- },
- { args: { view: "dedup" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_append_note",
- calls: one({ path: "notes/shared.md", content: "probe append" }, REASON.writerEcho),
- },
- {
- name: "brain_apply_evidence",
- calls: one(
- { pref_id: "pref-shared", artifact: "[[notes/shared.md]]", result: "applied" },
- REASON.writerEcho,
- ),
- },
- { name: "brain_audit", calls: one({ pref_id: "pref-shared" }, REASON.callerNamedArtifact) },
- { name: "brain_backlinks", calls: one({ id: SHARED_ID }, REASON.ownerFiltered) },
- {
- name: "brain_benchmark",
- calls: one(
- { operation: "run", dataset: "datasets/probe-absent.jsonl" },
- REASON.configuredCorpus,
- ),
- },
- {
- name: "brain_bridges",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "discover" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "accept", source: "notes/shared.md", target: "notes/owned-a.md" },
- reason: REASON.ownerlessLane,
- },
- {
- args: { operation: "dismiss", source: "notes/shared.md", target: "notes/owned-a.md" },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_claims",
- calls: [
- { args: { operation: "current" }, reason: REASON.ownerFiltered },
- { args: { operation: "at", at: LOG_EVENT_DATE }, reason: REASON.ownerFiltered },
- { args: { operation: "history" }, reason: REASON.ownerFiltered },
- { args: { operation: "replaced", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
- { args: { operation: "contests", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
- { args: { operation: "rebuild" }, reason: REASON.aggregateOnly },
- ],
- },
- {
- name: "brain_clusters",
- calls: [
- { args: { operation: "list" }, reason: REASON.aggregateOnly },
- { args: { operation: "run" }, reason: REASON.ownerFiltered },
- ],
- },
- { name: "brain_codegraph_report", calls: one({}, REASON.configuredCorpus) },
- {
- name: "brain_context_pack_outcome",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "summary" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "post", sample_id: "probe-sample", first_pass_success: true },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_context_presets",
- calls: [
- { args: { operation: "show" }, reason: REASON.catalog },
- { args: { operation: "suggest" }, reason: REASON.catalog },
- { args: { operation: "diff" }, reason: REASON.catalog },
- ],
- },
- {
- name: "brain_context_receipts",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "summary" }, reason: REASON.ownerlessLane },
- { args: { operation: "show", id: "rcpt-probe-absent" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_create_note",
- calls: one({ path: "notes/probe-created.md" }, REASON.writerEcho),
- },
- {
- name: "brain_dead_ends",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "record", approach: "probe approach", reason: "probe reason" },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_decision",
- calls: [
- { args: { action: "list" }, reason: REASON.ownerlessLane },
- { args: { action: "show", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "history" }, reason: REASON.ownerlessLane },
- { args: { action: "recall" }, reason: REASON.ownerlessLane },
- { args: { action: "similar", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "compare", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "outcome", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "rate", id: "dec-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "record", title: "probe decision" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_delete_by_source",
- calls: one({ source_file: "sources/paper.md" }, REASON.writerEcho),
- },
- {
- name: "brain_derive_fact",
- calls: one(
- {
- slug: "probe-derived",
- topic: "probe",
- principle: "probe derived principle",
- premises: [`[[${SHARED_ID}]]`],
- level: "deduced",
- },
- REASON.writerEcho,
- ),
- },
- {
- name: "brain_design_note",
- calls: [
- // The grounding stores carry no `owner:`, but the plan envelope's
- // `link_candidates` names Brain artifact ids - so this recipe DOES
- // reach owner-taggable content and is filtered, rather than being
- // unable to name it.
- { args: { topic: "probe topic" }, reason: REASON.ownerFiltered },
- {
- args: {
- topic: "probe topic",
- note: {
- title: "Probe",
- alternatives: [
- {
- name: "only",
- approach: "probe approach",
- tradeoffs: "probe tradeoffs",
- recommended: true,
- },
- ],
- },
- },
- reason: REASON.writerEcho,
- label: "commit",
- },
- ],
- },
- { name: "brain_diarize", calls: one({ entity: "probe-entity" }, REASON.ownerlessLane) },
- {
- name: "brain_distill_source",
- calls: one({ source_path: "sources/paper.md", claims: ["probe claim"] }, REASON.writerEcho),
- },
- {
- name: "brain_doctor",
- calls: [
- { args: {}, reason: REASON.ownerFiltered },
- { args: { strict: true }, reason: REASON.ownerFiltered },
- { args: { repair: true }, reason: REASON.ownerFiltered },
- ],
- },
- {
- name: "brain_dream",
- calls: [
- { args: { action: "list" }, reason: REASON.aggregateOnly },
- { args: { action: "run", dry_run: true }, reason: REASON.ownerFiltered },
- { args: { action: "stage" }, reason: REASON.ownerFiltered },
- { args: { action: "validate", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
- { args: { action: "apply", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
- { args: { action: "discard", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
- { args: { action: "retriage", run_id: "run-probe-absent" }, reason: REASON.aggregateOnly },
- ],
- },
- {
- name: "brain_entity",
- calls: [
- { args: { view: "list" }, reason: REASON.ownerlessLane },
- { args: { view: "get", query: "probe-entity" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_eval",
- calls: one({ dataset: "datasets/probe-absent.jsonl" }, REASON.configuredCorpus),
- },
- { name: "brain_event_trace", calls: one({ date: LOG_EVENT_DATE }, REASON.ownerFiltered) },
- {
- name: "brain_expire",
- calls: one(
- { id: `sig-2026-05-01-${NEUTRAL_SIGNAL_SLUG}`, expires: "2030-01-01" },
- REASON.callerNamedArtifact,
- ),
- },
- {
- name: "brain_extract_signals",
- calls: [
- { args: { session: "sess-probe" }, reason: REASON.sessionLane },
- {
- args: {
- session: "sess-probe",
- items: [
- {
- topic: "probe",
- signal: "positive",
- principle: "probe principle",
- confidence: 0.9,
- },
- ],
- },
- reason: REASON.writerEcho,
- label: "commit",
- },
- ],
- },
- {
- name: "brain_feedback",
- calls: one(
- { topic: "probe", signal: "positive", principle: "probe principle" },
- REASON.writerEcho,
- ),
- },
- { name: "brain_foresight", calls: one({}, REASON.aggregateOnly) },
- {
- name: "brain_generation_reports",
- calls: [
- { args: { action: "list" }, reason: REASON.ownerlessLane },
- { args: { action: "summary" }, reason: REASON.ownerlessLane },
- {
- args: {
- action: "record",
- handoff_kind: "context_pack",
- ref: "probe-ref",
- agent: OWNER_B,
- prompt: "probe prompt",
- enable: true,
- },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- { name: "brain_health", calls: one({}, REASON.ownerFiltered) },
- {
- name: "brain_hygiene",
- calls: [
- { args: { mode: "scan" }, reason: REASON.ownerFiltered },
- { args: { mode: "refresh", dry_run: true }, reason: REASON.recompileLane },
- // The ids come from a LIVE scan of the seeded fixture. A literal
- // id here would select nothing, and a recipe that selects nothing
- // is how `apply` kept a green probe while planning against the
- // unfiltered report and retiring another owner's preference.
- { args: hygieneApplyArgs, label: "mode=apply", reason: REASON.ownerFiltered },
- ],
- },
- { name: "brain_idea_discovery", calls: one({}, REASON.ownerFiltered) },
- { name: "brain_idea_lineage", calls: one({ id: SHARED_ID }, REASON.callerNamedArtifact) },
- {
- name: "brain_ingest_batch_plan",
- calls: one({ source_dir: "sources" }, REASON.configuredCorpus),
- },
- {
- name: "brain_ingest_source",
- calls: one(
- { source_path: "sources/paper.md", summary: "probe summary", entities: [] },
- REASON.writerEcho,
- ),
- },
- {
- name: "brain_intake_entities",
- calls: one({ entities: [], source: "sources/paper.md" }, REASON.writerEcho),
- },
- { name: "brain_intent_review", calls: one({}, REASON.signalCluster) },
- {
- name: "brain_intention",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "show" }, reason: REASON.ownerlessLane },
- { args: { operation: "set", text: "probe intention" }, reason: REASON.ownerlessLane },
- { args: { operation: "move", scope: "probe-scope" }, reason: REASON.ownerlessLane },
- ],
- },
- { name: "brain_knowledge_gaps", calls: one({}, REASON.aggregateOnly) },
- {
- name: "brain_labels",
- calls: [
- { args: { operation: "show", path: "notes/shared.md" }, reason: REASON.callerNamedArtifact },
- {
- args: {
- operation: "assign",
- path: "notes/shared.md",
- dimension: "probe",
- value: "probe",
- },
- reason: REASON.callerNamedArtifact,
- },
- {
- args: { operation: "remove", path: "notes/shared.md", dimension: "probe" },
- reason: REASON.callerNamedArtifact,
- },
- ],
- },
- {
- name: "brain_lifecycle",
- calls: [
- { args: { action: "curator" }, reason: REASON.aggregateOnly },
- { args: { action: "tip", id: SHARED_ID }, reason: REASON.callerNamedArtifact },
- {
- args: { action: "tombstone", path: "notes/shared.md", reason: "probe" },
- reason: REASON.writerEcho,
- },
- {
- args: {
- action: "supersede",
- predecessor: "notes/shared.md",
- successor: `[[${SHARED_ID}]]`,
- reason: "probe",
- },
- reason: REASON.writerEcho,
- },
- {
- args: {
- action: "temporal-replace",
- predecessor: "notes/shared.md",
- successor: "notes/renamed.md",
- at: LOG_EVENT_DATE,
- },
- reason: REASON.writerEcho,
- },
- ],
- },
- {
- name: "brain_maintenance",
- calls: [
- { args: { operation: "status" }, reason: REASON.aggregateOnly },
- { args: { operation: "run", force: true }, reason: REASON.aggregateOnly },
- ],
- },
- { name: "brain_mcp_landscape", calls: one({}, REASON.catalog) },
- {
- name: "brain_memory_bridge",
- calls: [
- { args: {}, reason: REASON.writerEcho },
- {
- args: { action: "add", target: "memory", content: "probe memory" },
- reason: REASON.writerEcho,
- },
- {
- args: { action: "replace", target: "memory", content: "probe memory" },
- reason: REASON.writerEcho,
- },
- ],
- },
- { name: "brain_moc_audit", calls: one({ id: HUB_ID }, REASON.ownerFiltered) },
- { name: "brain_note", calls: one({ text: "probe note" }, REASON.writerEcho) },
- {
- name: "brain_note_lifecycle",
- calls: [
- {
- args: { action: "rename", path: "notes/shared.md", to: "notes/renamed.md" },
- reason: REASON.writerEcho,
- },
- {
- args: { action: "move", path: "notes/shared.md", to: "notes/moved.md" },
- reason: REASON.writerEcho,
- },
- { args: { action: "archive", path: "notes/shared.md" }, reason: REASON.writerEcho },
- { args: { action: "delete", path: "notes/shared.md" }, reason: REASON.writerEcho },
- ],
- },
- {
- name: "brain_obligation",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "show", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "add", title: "probe obligation", cadence: "weekly" },
- reason: REASON.ownerlessLane,
- },
- { args: { operation: "done", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
- { args: { operation: "remove", slug: "probe-obligation" }, reason: REASON.ownerlessLane },
- ],
- },
- { name: "brain_observed_use", calls: one({ entries: [] }, REASON.writerEcho) },
- {
- name: "brain_pinned_context",
- calls: [
- { args: { operation: "read" }, reason: REASON.ownerlessLane },
- { args: { operation: "write", content: "probe pinned" }, reason: REASON.ownerlessLane },
- { args: { operation: "append", content: "probe pinned" }, reason: REASON.ownerlessLane },
- { args: { operation: "clear" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_procedural_graph",
- calls: [
- { args: { operation: "show" }, reason: REASON.ownerlessLane },
- { args: { operation: "rebuild" }, reason: REASON.ownerlessLane },
- { args: { operation: "hints" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_procedural_memory",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "reconcile" }, reason: REASON.ownerlessLane },
- { args: { operation: "mark_used", id: "proc-probe-absent" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "mark_outcome", id: "proc-probe-absent", outcome: "success" },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_recall_feedback",
- calls: one({ query: QUERY, result_path: "notes/shared.md", verdict: "up" }, REASON.writerEcho),
- },
- {
- name: "brain_recall_telemetry",
- calls: [
- { args: { operation: "summary" }, reason: REASON.ownerlessLane },
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "gate_list" }, reason: REASON.ownerlessLane },
- { args: { operation: "gate_summary" }, reason: REASON.ownerlessLane },
- { args: { operation: "observed_reuse" }, reason: REASON.ownerlessLane },
- { args: { operation: "cost" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_recurrence",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "show", content_hash: "probe-hash" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "learn", content_hash: "probe-hash", scope: "probe" },
- reason: REASON.ownerlessLane,
- },
- {
- args: { operation: "forget", content_hash: "probe-hash", scope: "probe" },
- reason: REASON.ownerlessLane,
- },
- { args: { operation: "purge_source", source_id: "probe" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_research_report",
- calls: one(
- { title: "probe report", sources: ["sources/paper.md"], findings: ["probe finding"] },
- REASON.writerEcho,
- ),
- },
- { name: "brain_retention", calls: one({}, REASON.ownerFiltered) },
- { name: "brain_review_candidates", calls: one({}, REASON.ownerFiltered) },
- {
- name: "brain_route_metrics",
- calls: [
- { args: { operation: "summary" }, reason: REASON.ownerlessLane },
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_scaffold_stub",
- calls: [
- { args: { action: "list" }, reason: REASON.ownerFiltered },
- // A neutral target: naming the marker here would be the caller's
- // own argument echoed back by the writer, not a disclosure.
- { args: { action: "write", target: "Projects/ProbeStub" }, reason: REASON.writerEcho },
- ],
- },
- {
- name: "brain_secrets",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "run", name: "probe-secret", command: ["true"] },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_session_checkpoint",
- calls: one({ session_id: "sess-probe" }, REASON.writerEcho),
- },
- {
- name: "brain_skill_proposals",
- calls: [
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- { args: { operation: "learn" }, reason: REASON.ownerlessLane },
- { args: { operation: "usage" }, reason: REASON.ownerlessLane },
- { args: { operation: "recover" }, reason: REASON.ownerlessLane },
- { args: { operation: "evidence", slug: "probe-proposal" }, reason: REASON.ownerlessLane },
- { args: { operation: "accept", slug: "probe-proposal" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "reject", slug: "probe-proposal", note: "probe" },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- { name: "brain_sources", calls: one({}, REASON.signalAuthorship) },
- { name: "brain_stale_scan", calls: one({}, REASON.ownerFiltered) },
- { name: "brain_status", calls: one({}, REASON.aggregateOnly) },
- { name: "brain_switch_vault", calls: one({ name: "probe-profile" }, REASON.writerEcho) },
- {
- name: "brain_tension",
- calls: [
- { args: { action: "list" }, reason: REASON.ownerlessLane },
- { args: { action: "detect" }, reason: REASON.ownerlessLane },
- { args: { action: "show", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "confirm", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "dismiss", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { action: "resolve", id: "tension-probe-absent" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_tiers",
- calls: [
- { args: { operation: "check" }, reason: REASON.aggregateOnly },
- { args: { operation: "restore", path: "notes/shared.md" }, reason: REASON.aggregateOnly },
- { args: { operation: "accept", path: "notes/shared.md" }, reason: REASON.aggregateOnly },
- ],
- },
- {
- name: "brain_token_impact",
- calls: [
- { args: { operation: "summary" }, reason: REASON.ownerlessLane },
- { args: { operation: "list" }, reason: REASON.ownerlessLane },
- {
- args: { operation: "record", baseline_tokens: 100, packed_tokens: 50 },
- reason: REASON.ownerlessLane,
- },
- { args: { operation: "outcome", outcome: "first_pass" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_trigger",
- calls: [
- { args: triggerQueueArgs("list"), label: "operation=list", reason: REASON.ownerFiltered },
- { args: { operation: "scan" }, reason: REASON.ownerFiltered },
- {
- args: triggerQueueArgs("history", true),
- label: "operation=history",
- reason: REASON.ownerFiltered,
- },
- { args: { operation: "acknowledge", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { operation: "dismiss", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { operation: "act", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { operation: "suppress", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { operation: "unsuppress", id: "trg-probe-absent" }, reason: REASON.ownerlessLane },
- ],
- },
- {
- name: "brain_truth",
- calls: [
- { args: { operation: "slots" }, reason: REASON.ownerlessLane },
- { args: { operation: "conflicts" }, reason: REASON.ownerlessLane },
- { args: { operation: "collisions" }, reason: REASON.ownerlessLane },
- { args: { operation: "aggregate" }, reason: REASON.ownerlessLane },
- {
- args: {
- operation: "ingest",
- entity: "probe-entity",
- aspect: "probe-aspect",
- value: "probe",
- source: "[[notes/shared.md]]",
- },
- reason: REASON.ownerlessLane,
- },
- ],
- },
- {
- name: "brain_tune",
- calls: [
- { args: { operation: "status" }, reason: REASON.aggregateOnly },
- { args: { operation: "reset" }, reason: REASON.aggregateOnly },
- { args: { operation: "run" }, reason: REASON.aggregateOnly },
- ],
- },
- { name: "brain_unlinked_mentions", calls: one({ id: SHARED_ID }, REASON.ownerFiltered) },
- {
- name: "brain_update_note",
- calls: one({ path: "notes/shared.md", content: "probe update" }, REASON.writerEcho),
- },
- { name: "brain_watchdog", calls: one({}, REASON.aggregateOnly) },
- { name: "brain_write_batch", calls: one({ operations: [] }, REASON.writerEcho) },
- {
- name: "brain_write_session",
- calls: [
- { args: { op: "list" }, reason: REASON.ownerlessLane },
- { args: { op: "status", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { op: "open", target: "Brain/probe-session.md" }, reason: REASON.ownerlessLane },
- {
- args: { op: "submit", session_id: "ws-probe-absent", text: "probe text" },
- reason: REASON.ownerlessLane,
- },
- { args: { op: "approve", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
- { args: { op: "abandon", session_id: "ws-probe-absent" }, reason: REASON.ownerlessLane },
- ],
- },
- { name: "get_skill", calls: one({ name: "open-second-brain" }, REASON.catalog) },
- { name: "list_skills", calls: one({}, REASON.catalog) },
- { name: "schema_apply_mutations", calls: one({ mutations: [] }, REASON.writerEcho) },
- {
- name: "schema_inspect",
- calls: [
- { args: { view: "stats" }, reason: REASON.aggregateOnly },
- { args: { view: "graph" }, reason: REASON.aggregateOnly },
- { args: { view: "lint" }, reason: REASON.aggregateOnly },
- { args: { view: "orphans" }, reason: REASON.aggregateOnly },
- { args: { view: "packs" }, reason: REASON.catalog },
- { args: { view: "active_pack" }, reason: REASON.catalog },
- { args: { view: "explain_type", type: "brain-preference" }, reason: REASON.catalog },
- ],
- },
- { name: "second_brain_capabilities", calls: one({}, REASON.catalog) },
- { name: "second_brain_status", calls: one({}, REASON.aggregateOnly) },
- { name: "skills_attach", calls: one({ query: QUERY }, REASON.catalog) },
- { name: "tool_hydrate", calls: one({}, REASON.catalog) },
- { name: "vault_health", calls: one({}, REASON.aggregateOnly) },
-];
-
-/**
- * Every entry the isolation probe drives, checked at module load.
- *
- * Both unasserted buckets, in one list: `SCOPED_SURFACES` is excluded
- * because its members are already driven, per surface, by the fifteen
- * behavioural tests below.
- */
-const PROBE_ENTRIES: ReadonlyArray<ProbeEntry> = [
- ...UNSCOPED_CONTENT.map((e) => assertProbeEntry("UNSCOPED_CONTENT", e)),
- ...NON_CONTENT.map((e) => assertProbeEntry("NON_CONTENT", e)),
-];
-
const TOOLS = buildToolTable("full");
const tool = (name: string): ToolDefinition => {
const found = TOOLS.find((t) => t.name === name);
@@ -1713,24 +707,6 @@ function probeArgs(recipe: ProbeCall): Record<string, unknown> {
return typeof recipe.args === "function" ? recipe.args(vault) : recipe.args;
}
-/**
- * A recipe's test name: the tool plus whatever selects the code path.
- *
- * Read off the recipe rather than hand-written, so a recipe added later
- * cannot be the one with a name that no longer matches its arguments.
- */
-const DISPATCH_KEYS = ["mode", "view", "operation", "action", "op"] as const;
-
-function probeLabel(name: string, recipe: ProbeCall, index: number): string {
- if (recipe.label !== undefined) return `${name} ${recipe.label}`;
- if (typeof recipe.args === "function") return `${name} #${index}`;
- for (const key of DISPATCH_KEYS) {
- const value = recipe.args[key];
- if (typeof value === "string") return `${name} ${key}=${value}`;
- }
- return index === 0 ? name : `${name} #${index}`;
-}
-
test("the probe's own fixture puts the marker in front of an unscoped caller", async () => {
setGate(GATE_MODE.off);
await seedTwoOwnerFixture();
diff --git a/tests/mcp/brain-bridges-visibility.test.ts b/tests/mcp/brain-bridges-visibility.test.ts
new file mode 100644
index 00000000..2ce67160
--- /dev/null
+++ b/tests/mcp/brain-bridges-visibility.test.ts
@@ -0,0 +1,98 @@
+/**
+ * Root closure over `brain_bridges` (private-is-not-a-suggestion).
+ *
+ * The registry classified this tool COVERED off its `list` mode alone.
+ * `list` reads `Brain/proposals/bridges.md` by path and asks the rule at
+ * the site of the read; `discover` returned `discoverBridges()`'s
+ * proposals verbatim, each naming two pages by vault-relative path off
+ * the vec index - which keeps reserved pages by design, because the
+ * `documents.visibility` column reports what the index measured rather
+ * than excluding what it holds.
+ *
+ * Detection stays vault-wide and the shared artifact is still written
+ * unfiltered: a bridge proposed from the visible half of a link graph
+ * would differ per caller, and the file is one file. The rule is applied
+ * to what the CALLER is told, which is the shape `brain_clusters run`
+ * already uses - and a proposal with one end withheld is dropped whole,
+ * because a bridge reported with one end missing is not a narrower true
+ * finding but a false one.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../../src/core/graph/transport-reach.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
+import { BRAIN_TOOLS } from "../../src/mcp/brain-tools.ts";
+import type { ServerContext } from "../../src/mcp/tool-contract.ts";
+
+const RESERVED = "beta-deploy.md";
+const OPEN = "alpha-deploy.md";
+
+let vault: string;
+let configHome: string;
+let configPath: string;
+
+beforeEach(async () => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-bridges-vis-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-bridges-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(
+ configPath,
+ [
+ `vault: ${vault}`,
+ "search_semantic_enabled: true",
+ "embedding_provider: local",
+ "embedding_dimension: 256",
+ "",
+ ].join("\n"),
+ );
+ writeFileSync(
+ join(vault, OPEN),
+ "# Canary deployment runbook\n\nShip the canary release to one production instance, watch error rates, expand the deployment gradually, roll back on regression.\n",
+ );
+ writeFileSync(
+ join(vault, RESERVED),
+ `---\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]\n---\n\n# Deployment safety checklist\n\nCanary release first: one production instance, watch error rates, expand deployment gradually, roll back the release on regression.\n`,
+ );
+ await indexVault(resolveSearchConfig({ vault, configPath }), { embeddings: true });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+async function discover(reach: TransportReach): Promise<string> {
+ const tool = BRAIN_TOOLS.find((t) => t.name === "brain_bridges")!;
+ const ctx: ServerContext = { vault, reach, configPath, repoRoot: null };
+ return JSON.stringify(await tool.handler(ctx, { operation: "discover", min_similarity: 0.5 }));
+}
+
+describe("brain_bridges operation=discover", () => {
+ test("proposes the reserved pair at local reach", async () => {
+ const out = await discover(TRANSPORT_REACH.local);
+ expect(out).toContain(RESERVED);
+ expect(out).toContain(OPEN);
+ });
+
+ test("names neither end of that pair at remote reach", async () => {
+ const out = await discover(TRANSPORT_REACH.remote);
+ expect(out).not.toContain(RESERVED);
+ // Dropped WHOLE: the open end goes with it rather than being
+ // reported as a bridge to nowhere.
+ expect(JSON.parse(out).proposals).toEqual([]);
+ });
+
+ test("the corpus-size count is the same measurement at both reaches", async () => {
+ // `scanned_candidates` names no page and detection is vault-wide, so
+ // it is not a per-caller number and is not withheld.
+ const local = JSON.parse(await discover(TRANSPORT_REACH.local));
+ const remote = JSON.parse(await discover(TRANSPORT_REACH.remote));
+ expect(remote.scanned_candidates).toBe(local.scanned_candidates);
+ });
+});
diff --git a/tests/mcp/reach-refusal.test.ts b/tests/mcp/reach-refusal.test.ts
new file mode 100644
index 00000000..ca266675
--- /dev/null
+++ b/tests/mcp/reach-refusal.test.ts
@@ -0,0 +1,185 @@
+/**
+ * The transport reach is MINTED, never parsed
+ * (private-is-not-a-suggestion, unit 2).
+ *
+ * Which pages a caller may read now depends on how that caller reached
+ * this process. That fact is held by the transport and by nothing else,
+ * so each transport mints it and a reach-shaped member in a tool's
+ * arguments is refused BY NAME - the rule
+ * `src/mcp/owner-scope-refusal.ts` states once for owner identity: a
+ * trust claim echoed back from the request is not a trust claim.
+ *
+ * Refused rather than ignored, because a silently dropped argument
+ * answers a question nobody asked, and refused rather than honoured,
+ * because honouring it would make the boundary a request parameter.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+
+import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
+import { httpBindReach, startHttp } from "../../src/mcp/http.ts";
+import { MCPError } from "../../src/mcp/protocol.ts";
+import {
+ REACH_REFUSAL,
+ RESERVED_REACH_ARGUMENTS,
+ assertNoCallerSuppliedReach,
+ findCallerSuppliedReach,
+} from "../../src/mcp/reach-refusal.ts";
+import { MCPServer } from "../../src/mcp/server.ts";
+import { STDIO_TRANSPORT_REACH, serveStdio } from "../../src/mcp/stdio.ts";
+import { contextReach } from "../../src/mcp/tool-contract.ts";
+import type { ToolDefinition } from "../../src/mcp/tool-contract.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "reach-refusal-"));
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+describe("a context with no minted reach", () => {
+ test("fails closed to remote", () => {
+ // A hand-built context - an embedded caller, a test - established
+ // nothing about who is asking, and an unestablished reach is not the
+ // absence of one.
+ expect(contextReach({ vault, configPath: null, repoRoot: null })).toBe(TRANSPORT_REACH.remote);
+ });
+
+ test("is what a server built without a transport reports", () => {
+ expect(contextReach(new MCPServer({ vault }).context)).toBe(TRANSPORT_REACH.remote);
+ });
+});
+
+describe("a minted reach reaches the handler context", () => {
+ for (const reach of [TRANSPORT_REACH.local, TRANSPORT_REACH.remote]) {
+ test(`${reach} survives onto ServerContext`, () => {
+ const server = new MCPServer({ vault }, { reach });
+ expect(contextReach(server.context)).toBe(reach);
+ });
+ }
+});
+
+describe("each transport mints its own reach", () => {
+ test("stdio mints local: the caller already started this process", async () => {
+ const stdin = new PassThrough();
+ const stdout = new PassThrough();
+ stdout.resume();
+ let minted: string | undefined;
+ const loop = serveStdio(
+ { vault },
+ {
+ stdin,
+ stdout,
+ onStart: (handle) => {
+ minted = handle.reach;
+ },
+ },
+ );
+ stdin.end();
+ await loop;
+ expect(minted).toBe(STDIO_TRANSPORT_REACH);
+ expect(STDIO_TRANSPORT_REACH).toBe(TRANSPORT_REACH.local);
+ });
+
+ test("an HTTP bind mints on the loopback question alone", () => {
+ for (const host of ["127.0.0.1", "localhost", "::1", "[::1]:8080", "LOCALHOST"]) {
+ expect(httpBindReach(host)).toBe(TRANSPORT_REACH.local);
+ }
+ for (const host of ["0.0.0.0", "192.168.1.10", "example.internal", "::"]) {
+ expect(httpBindReach(host)).toBe(TRANSPORT_REACH.remote);
+ }
+ });
+
+ test("a live loopback bind reports the reach it minted", async () => {
+ const handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
+ try {
+ expect(handle.reach).toBe(TRANSPORT_REACH.local);
+ } finally {
+ await handle.close();
+ }
+ });
+
+ test("a runtime option cannot override what the transport established", async () => {
+ const stdin = new PassThrough();
+ const stdout = new PassThrough();
+ stdout.resume();
+ let minted: string | undefined;
+ const loop = serveStdio(
+ { vault },
+ {
+ stdin,
+ stdout,
+ onStart: (handle) => {
+ minted = handle.reach;
+ },
+ },
+ { reach: TRANSPORT_REACH.remote },
+ );
+ stdin.end();
+ await loop;
+ expect(minted).toBe(TRANSPORT_REACH.local);
+ });
+});
+
+/** A tool whose schema is OPEN, so the unknown-argument gate says nothing. */
+const OPEN_SCHEMA_TOOL: ToolDefinition = Object.freeze({
+ name: "open_schema_probe",
+ description: "probe",
+ inputSchema: { type: "object", properties: {} },
+ handler: () => ({}),
+});
+
+describe("a caller-supplied reach is refused by name", () => {
+ test("every reserved spelling is found, whatever its case or separator", () => {
+ for (const name of RESERVED_REACH_ARGUMENTS) {
+ expect(findCallerSuppliedReach({ [name]: TRANSPORT_REACH.local })).toEqual([name]);
+ }
+ expect(findCallerSuppliedReach({ TRANSPORT_REACH: "local" })).toEqual(["TRANSPORT_REACH"]);
+ expect(findCallerSuppliedReach({ "transport-reach": "local" })).toEqual(["transport-reach"]);
+ });
+
+ test("an ordinary argument is not mistaken for one", () => {
+ // `disclosure` is the progressive result-DEPTH mode and is a real
+ // argument on the recall surfaces; refusing it would break them.
+ expect(
+ findCallerSuppliedReach({ query: "x", disclosure: "cards", visibility: ["team"] }),
+ ).toEqual([]);
+ });
+
+ test("the refusal names the argument, the reason, and what mints it", () => {
+ let thrown: unknown;
+ try {
+ assertNoCallerSuppliedReach(OPEN_SCHEMA_TOOL, { reach: TRANSPORT_REACH.local });
+ } catch (exc) {
+ thrown = exc;
+ }
+ expect(thrown).toBeInstanceOf(MCPError);
+ const err = thrown as MCPError;
+ expect(err.message).toContain(OPEN_SCHEMA_TOOL.name);
+ expect(err.message).toContain("reach");
+ expect(err.message).toContain(REACH_REFUSAL);
+ const data = err.data as { readonly refused_arguments: ReadonlyArray<string> };
+ expect(data.refused_arguments).toEqual(["reach"]);
+ });
+
+ test("an open schema is refused too, so this is not the unknown-argument gate", () => {
+ // The unknown-argument gate reads `additionalProperties: false` and
+ // says nothing about an open schema. This rule does not depend on the
+ // schema at all.
+ expect(() => assertNoCallerSuppliedReach(OPEN_SCHEMA_TOOL, { reach: "local" })).toThrow(
+ MCPError,
+ );
+ expect(() => assertNoCallerSuppliedReach(OPEN_SCHEMA_TOOL, { query: "x" })).not.toThrow();
+ });
+
+ test("the live server refuses it on the tool-call seam", async () => {
+ const server = new MCPServer({ vault }, { reach: TRANSPORT_REACH.local });
+ await expect(server.callTool("brain_search", { query: "x", reach: "local" })).rejects.toThrow(
+ new RegExp(REACH_REFUSAL),
+ );
+ });
+});
diff --git a/tests/mcp/visibility-matrix.test.ts b/tests/mcp/visibility-matrix.test.ts
new file mode 100644
index 00000000..9e44c979
--- /dev/null
+++ b/tests/mcp/visibility-matrix.test.ts
@@ -0,0 +1,643 @@
+/**
+ * The visibility axis of the tool-surface matrix
+ * (private-is-not-a-suggestion, unit 9).
+ *
+ * `tests/mcp/agent-scope-matrix.test.ts` drives every tool in the live
+ * table against a two-OWNER fixture. Its subject is ownership; its
+ * fixture carries no `visibility:`-tagged page, it asserts nothing about
+ * the MCP `_meta` response member, and it drives no federated caller. So
+ * a page reserved against remote reads could have leaked through any of
+ * the hundred-odd surfaces it sweeps and every one of its assertions
+ * would still have been green.
+ *
+ * This is the second pass over the same enumeration - the recipes are
+ * shared through `tests/helpers/tool-probe-catalogue.ts` rather than
+ * copied, because a second copy of "what is the whole surface" is the
+ * enumeration defect the first matrix was built to remove.
+ *
+ * ## A sibling file rather than a second axis in the first
+ *
+ * The design left this open, to be decided on whether the two axes could
+ * share one fixture without either one's assertions becoming
+ * conditional. They cannot. The owner matrix builds its contexts without
+ * a transport reach, which resolves to the narrowest - so the moment its
+ * fixture gained a reserved page, every owner assertion would have had to
+ * say which reach it was asking at, and the gate-off half of its
+ * differential would have been measuring two rules at once.
+ *
+ * ## The four channels, asserted in one place
+ *
+ * Every probe here goes through the real JSON-RPC `tools/call` path with
+ * a progress token attached, and the assertion is made over the WHOLE
+ * serialised response. That covers all four channels a marker could ride
+ * out on in a single check: `structuredContent`, the rendered
+ * `content[].text`, the error `message` a throw produces, and the `_meta`
+ * member the progress refusal travels in - which no prior sweep looked
+ * at, and which is a live channel on this transport.
+ *
+ * ## Two buckets, both executed
+ *
+ * A blanket "no tool may name a reserved page" would have been a claim
+ * this wave does not deliver, and the first run of this file proved it:
+ * twenty-eight recipes still named one. They belong to surfaces the
+ * visibility registry classifies as EXCLUDED, and `search check` reports
+ * that population to operators - so the honest shape is the same two
+ * buckets the owner matrix uses, each with an executed claim:
+ *
+ * - a tool the registry calls COVERED must withhold. That is the
+ * boundary, swept over every recipe those tools have.
+ * - every other recipe's verdict is MEASURED, in
+ * {@link STILL_NAMED_AT_REMOTE}, and asserted in BOTH directions. A
+ * recipe leaving that list is the wave that covered it; one joining
+ * it is a regression; and either way the diff says so rather than a
+ * count quietly moving.
+ *
+ * ## What this file does NOT establish, stated rather than implied
+ *
+ * The REACHABILITY half - that the fixture actually puts the marker in
+ * front of a local caller, without which every `not.toContain` would be a
+ * clean sweep over an empty fixture - is NOT per-recipe. The visibility
+ * axis has no per-call classification of its own, and inventing two
+ * hundred of them would be two hundred unexecuted labels.
+ *
+ * So it is measured instead, in two places. A named subset
+ * ({@link RECIPES_REACHING_RESERVED_CONTENT}) is asserted recipe by
+ * recipe, and {@link RECIPES_REACHING_RESERVED_AT_LOCAL} bounds how many
+ * of ALL recipes reach the page at a reach that reaches it. That second
+ * number is the honest size of this sweep's enforcement weight: most
+ * recipes never touch the reserved page even locally, so most of the
+ * remote assertions are coverage of the enumeration rather than of the
+ * rule. Naming the subset without the count understated the gap by two
+ * orders of magnitude, which a review found by measuring it.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { appendLogEvent } from "../../src/core/brain/log.ts";
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { addRecallSource } from "../../src/core/brain/portability/recall-sources.ts";
+import { writePreference } from "../../src/core/brain/preference.ts";
+import { writeSignal } from "../../src/core/brain/signal.ts";
+import {
+ BRAIN_CONFIDENCE,
+ BRAIN_LOG_EVENT_KIND,
+ BRAIN_PREFERENCE_STATUS,
+} from "../../src/core/brain/types.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../../src/core/graph/transport-reach.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
+import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";
+import { JSONRPC_VERSION } from "../../src/mcp/protocol.ts";
+import { MCPServer } from "../../src/mcp/server.ts";
+import { PROGRESS_META_KEY } from "../../src/mcp/progress.ts";
+
+/** The result member the progress refusal rides on, spelled once. */
+const PROGRESS_META_RESULT_MEMBER = "_meta";
+import { buildToolTable } from "../../src/mcp/tools.ts";
+import {
+ VISIBILITY_SURFACE_CATEGORY,
+ VISIBILITY_SURFACE_KIND,
+ VISIBILITY_SURFACE_REGISTRY,
+} from "../../src/core/search/visibility-surface-registry.ts";
+import {
+ NEUTRAL_SIGNAL_SLUG,
+ PROBE,
+ PROBE_ENTRIES,
+ PROBE_TERMS,
+ QUERY,
+ SHARED_ID,
+ SHARED_TITLE,
+ SHARED_TOPIC,
+ probeLabel,
+ type ProbeCall,
+ type ProbeEntry,
+} from "../helpers/tool-probe-catalogue.ts";
+
+/** HOME is pinned per file by convention; nothing pins it globally. */
+process.env["HOME"] = mkdtempSync(join(tmpdir(), "o2b-vis-matrix-home-"));
+
+/**
+ * The string this probe hunts for. It appears ONLY inside artifacts that
+ * carry the reserved visibility token - in their ids, paths, topics,
+ * titles and body prose - so one `not.toContain` catches every field a
+ * surface might name one of them in.
+ */
+const RESERVED_MARKER = "zzreservedmarkerzz";
+
+/** The UTC day the fixture's log event lands on. */
+const LOG_EVENT_DATE = "2026-05-04";
+
+/** Wall-clock ceiling for one probe; two entries do real work first. */
+const PROBE_TIMEOUT_MS = 30_000;
+
+const TOOLS = buildToolTable("full");
+
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+beforeEach(async () => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-vis-matrix-"));
+ vault = join(tmp, "vault");
+ configPath = join(tmp, "config.yaml");
+ for (const sub of ["preferences", "retired", "inbox", "log"]) {
+ mkdirSync(join(vault, "Brain", sub), { recursive: true });
+ }
+ mkdirSync(join(vault, "notes"), { recursive: true });
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ await seedReservedFixture();
+});
+
+afterEach(() => rmSync(tmp, { recursive: true, force: true }));
+
+function makePref(
+ slug: string,
+ overrides: Partial<Parameters<typeof writePreference>[1]> = {},
+): void {
+ writePreference(vault, {
+ slug,
+ topic: slug,
+ principle: `principle for ${slug}`,
+ created_at: "2026-05-01T00:00:00Z",
+ unconfirmed_until: "2026-05-08T00:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
+ confirmed_at: "2026-05-02T00:00:00Z",
+ applied_count: 1,
+ violated_count: 0,
+ last_evidence_at: "2026-05-02T00:00:00Z",
+ confidence: BRAIN_CONFIDENCE.high,
+ confidence_value: 0.8,
+ ...overrides,
+ });
+}
+
+/** Add frontmatter lines and a body to an artifact already on disk. */
+function patchArtifact(rel: string, frontmatter: ReadonlyArray<string>, body: string): void {
+ const abs = join(vault, rel);
+ const text = readFileSync(abs, "utf8");
+ const close = text.indexOf("\n---\n", "---\n".length);
+ expect(close, `${rel} has no frontmatter block`).toBeGreaterThan(0);
+ const head = frontmatter.length === 0 ? "" : `\n${frontmatter.join("\n")}`;
+ const tail = body.length === 0 ? "" : `\n${body}\n`;
+ writeFileSync(abs, text.slice(0, close) + head + text.slice(close) + tail);
+}
+
+/** The frontmatter line that reserves a page against remote reads. */
+const RESERVE_LINE = `visibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]`;
+
+/**
+ * The reserved-page fixture: the same artifact SHAPES the owner matrix
+ * seeds, tagged with the reserved visibility token instead of an `owner:`.
+ *
+ * The evidence signal is deliberately neutral-named and untagged, for the
+ * same reason it is ownerless there: a marker inside a shared artifact
+ * would make every assertion below a claim about something the caller is
+ * entitled to read.
+ */
+async function seedReservedFixture(): Promise<void> {
+ const reserved = `${RESERVED_MARKER}-r`;
+ const reservedOnSharedTopic = `${RESERVED_MARKER}-r2`;
+
+ writeSignal(vault, {
+ topic: NEUTRAL_SIGNAL_SLUG,
+ signal: "positive",
+ agent: "agent-a",
+ principle: "principle for the neutral evidence signal",
+ created_at: "2026-05-01T00:00:00Z",
+ date: "2026-05-01",
+ slug: NEUTRAL_SIGNAL_SLUG,
+ source: [`[[${SHARED_ID}]]`],
+ });
+
+ makePref("shared");
+ makePref("hub");
+ makePref(reserved, { evidenced_by: [`[[sig-2026-05-01-${NEUTRAL_SIGNAL_SLUG}]]`] });
+ makePref(reservedOnSharedTopic, { topic: SHARED_TOPIC });
+
+ patchArtifact(`Brain/preferences/${SHARED_ID}.md`, [`title: ${SHARED_TITLE}`], "");
+ patchArtifact(
+ `Brain/preferences/pref-${reserved}.md`,
+ [RESERVE_LINE, `supersedes: "[[${SHARED_ID}]]"`],
+ `See [[${SHARED_ID}]]. Also ${SHARED_TITLE} ${RESERVED_MARKER} here.`,
+ );
+ patchArtifact(`Brain/preferences/pref-${reservedOnSharedTopic}.md`, [RESERVE_LINE], "");
+ patchArtifact(
+ "Brain/preferences/pref-hub.md",
+ [],
+ `Hub. [[pref-${reserved}]] [[${SHARED_ID}]] [[missing-shared-member]]`,
+ );
+
+ writeFileSync(
+ join(brainDirs(vault).retired, `ret-${RESERVED_MARKER}-r.md`),
+ [
+ "---",
+ "kind: brain-retired",
+ `id: ret-${RESERVED_MARKER}-r`,
+ RESERVE_LINE,
+ "created_at: 2026-05-01T00:00:00Z",
+ "tags: []",
+ `topic: ${RESERVED_MARKER}-r`,
+ "principle: retired principle",
+ "provenance: observed",
+ "retired_at: 2026-05-03T00:00:00Z",
+ `retired_by: "[[${SHARED_ID}]]"`,
+ "retired_reason: superseded-by-context",
+ "_status: retired",
+ "_evidenced_by: []",
+ "---",
+ "",
+ `See [[${SHARED_ID}]] and ${SHARED_TITLE} ${RESERVED_MARKER}.`,
+ "",
+ ].join("\n"),
+ );
+
+ writeFileSync(join(vault, "notes", "shared.md"), `# Shared\n\n${QUERY} ${PROBE_TERMS} shared\n`);
+ writeFileSync(
+ join(vault, "notes", `${RESERVED_MARKER}-r.md`),
+ `---\n${RESERVE_LINE}\n---\n\n${QUERY} ${PROBE_TERMS} [[missing-${RESERVED_MARKER}-target]]\n`,
+ );
+
+ for (const slug of [reserved, reservedOnSharedTopic]) {
+ appendLogEvent(
+ vault,
+ {
+ timestamp: `${LOG_EVENT_DATE}T00:00:00Z`,
+ eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
+ body: {
+ path: `Brain/preferences/pref-${slug}.md`,
+ preference: `[[pref-${slug}]]`,
+ result: "applied",
+ },
+ },
+ { deviceId: "" },
+ );
+ }
+
+ await indexVault(resolveSearchConfig({ vault, configPath }), { force: true });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The recipes the owner matrix drives per-surface rather than through the
+// shared probe, spelled here so this axis covers the whole table.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The fourteen surfaces `SCOPED_SURFACES` names.
+ *
+ * The owner matrix drives them through bespoke behavioural tests rather
+ * than through its probe list, so the shared catalogue carries no recipes
+ * for them. It carries the OTHER ninety-nine, which is why they are not
+ * repeated here.
+ */
+const SCOPED_CALLS: ReadonlyArray<ProbeEntry> = [
+ { name: "brain_context", calls: [{ args: {}, reason: "no-argument session bootstrap" }] },
+ {
+ name: "brain_context_pack",
+ calls: [{ args: { max_tokens: 4000 }, reason: "packs Brain artifacts into a budget" }],
+ },
+ {
+ name: "brain_pre_compress_pack",
+ calls: [{ args: { top_k: 10 }, reason: "packs the pre-compression carry-over" }],
+ },
+ {
+ name: "brain_anticipatory_context",
+ calls: [{ args: { session_id: "sess-1" }, reason: "predicts the next turn's context" }],
+ },
+ {
+ name: "brain_brief",
+ calls: [{ args: { view: "morning" }, reason: "the session-start summary view" }],
+ },
+ {
+ name: "brain_retrieval_plan",
+ calls: [{ args: { question: QUERY }, reason: "plans retrieval for one question" }],
+ },
+ {
+ name: "brain_query",
+ calls: [
+ { args: { topic: SHARED_TOPIC }, reason: "a topic fans out to every preference on it" },
+ { args: { since: "2026-05-01" }, reason: "a log window names the artifacts it touched" },
+ ],
+ },
+ { name: "brain_search", calls: [{ args: { query: QUERY }, reason: "the ranked search root" }] },
+ {
+ name: "brain_search_expand",
+ calls: [
+ {
+ args: reservedChunkArgs,
+ label: "chunk_id=reserved",
+ reason: "the key-addressed drill-down over a reserved page's own chunk",
+ },
+ ],
+ },
+ {
+ name: "brain_file_context",
+ calls: [{ args: { file_path: PROBE }, reason: "prior work for a file about to be read" }],
+ },
+ {
+ name: "brain_deep_synthesis",
+ calls: [{ args: { topic: QUERY }, reason: "synthesises over the matched notes" }],
+ },
+ {
+ name: "brain_search_by_source",
+ calls: [{ args: { source_file: PROBE }, reason: "traces every page derived from one source" }],
+ },
+ { name: "second_brain_query", calls: [{ args: {}, reason: "the vault page listing" }] },
+ { name: "brain_agent_query", calls: [{ args: {}, reason: "the provenance roster" }] },
+];
+
+/**
+ * `brain_search_expand` arguments naming a chunk of the RESERVED page.
+ *
+ * A literal id would select nothing and the probe would go green over a
+ * drill-down that never touched the page - the "clean sweep over an empty
+ * fixture" the owner matrix's own recipes exist to prevent. The id is
+ * read at local reach, which is the only reach that can produce it.
+ */
+function reservedChunkArgs(vaultDir: string): Record<string, unknown> {
+ const chunkId = reservedChunkId(vaultDir);
+ return { chunk_id: chunkId };
+}
+
+let cachedChunkId: { readonly vault: string; readonly id: number } | null = null;
+
+function reservedChunkId(vaultDir: string): number {
+ if (cachedChunkId !== null && cachedChunkId.vault === vaultDir) return cachedChunkId.id;
+ // Resolved synchronously off the index the fixture just built: the
+ // reserved note is the only one carrying the marker in its path.
+ const config = resolveSearchConfig({ vault: vaultDir, configPath });
+ const db = new Database(config.dbPath, { readonly: true });
+ try {
+ const row = db
+ .query<{ id: number }, [string]>(
+ "SELECT c.id AS id FROM chunks c JOIN documents d ON d.id = c.document_id WHERE d.path LIKE ?1 ORDER BY c.id LIMIT 1",
+ )
+ .get(`%${RESERVED_MARKER}%`);
+ if (row === undefined || row === null) {
+ throw new Error("the reserved page produced no chunk");
+ }
+ cachedChunkId = { vault: vaultDir, id: row.id };
+ return row.id;
+ } finally {
+ db.close();
+ }
+}
+
+/** Every recipe this axis drives: the shared ninety-nine plus the fourteen. */
+const ALL_ENTRIES: ReadonlyArray<ProbeEntry> = [...PROBE_ENTRIES, ...SCOPED_CALLS];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The mechanism
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("the visibility matrix drives every tool exactly once", () => {
+ const named = ALL_ENTRIES.map((e) => e.name);
+ expect(new Set(named).size).toBe(named.length);
+ // Both directions: a NEW tool fails until it is driven here, and a
+ // REMOVED one fails until its entry goes.
+ expect(named.toSorted()).toEqual(TOOLS.map((t) => t.name).toSorted());
+});
+
+/**
+ * Drive one tool through the real `tools/call` path at `reach`, with a
+ * progress token attached, and return the whole serialised response.
+ *
+ * The token is what makes the `_meta` channel live: this server is built
+ * without a notification sink, so a request carrying one is answered with
+ * a refusal that rides in `result._meta` - a member no prior sweep looked
+ * at, and one more place a marker could have travelled.
+ */
+async function drive(
+ reach: TransportReach,
+ name: string,
+ args: Record<string, unknown>,
+): Promise<string> {
+ const server = new MCPServer({ vault, configPath }, { reach });
+ const response = await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "tools/call",
+ params: { name, arguments: args, _meta: { progressToken: "probe-token" } },
+ });
+ return JSON.stringify(response);
+}
+
+/** Resolve a recipe's arguments against the seeded fixture. */
+function probeArgs(recipe: ProbeCall): Record<string, unknown> {
+ return typeof recipe.args === "function" ? recipe.args(vault) : recipe.args;
+}
+
+/**
+ * The recipes hand-verified to put the marker in front of a LOCAL caller.
+ *
+ * Without these the sweep below could be clean because the fixture never
+ * reached the reserved page. They are the non-vacuity anchor, and the
+ * limit of that anchor is stated in the module docblock: it is a named
+ * subset, not a per-recipe derivation.
+ */
+const RECIPES_REACHING_RESERVED_CONTENT: ReadonlyArray<{
+ readonly name: string;
+ readonly args: Record<string, unknown>;
+}> = [
+ { name: "brain_search", args: { query: QUERY, visibility: [REMOTE_DENY_VISIBILITY_TOKEN] } },
+ { name: "brain_query", args: { since: "2026-05-01" } },
+ { name: "brain_backlinks", args: { id: SHARED_ID } },
+ { name: "second_brain_query", args: {} },
+];
+
+for (const probe of RECIPES_REACHING_RESERVED_CONTENT) {
+ test(`${probe.name}: the fixture reaches the reserved page at local reach`, async () => {
+ expect(await drive(TRANSPORT_REACH.local, probe.name, probe.args)).toContain(RESERVED_MARKER);
+ });
+}
+
+/**
+ * The surfaces the visibility registry classifies as COVERED: a read root
+ * reaches their content, so the reserved token is enforced on them and
+ * this probe holds them to it.
+ */
+const COVERED_TOOLS: ReadonlySet<string> = new Set(
+ VISIBILITY_SURFACE_REGISTRY.filter(
+ (e) =>
+ e.kind === VISIBILITY_SURFACE_KIND.mcpTool &&
+ e.category === VISIBILITY_SURFACE_CATEGORY.covered,
+ ).map((e) => e.surface),
+);
+
+/**
+ * The recipes that STILL name a reserved page at remote reach, measured.
+ *
+ * Every one of them belongs to a tool the registry classifies as
+ * excluded, and `search check` reports that population to operators in
+ * the honesty finding. Pinning them here as an EQUALITY - asserted in
+ * both directions - is what turns "some surfaces are not covered yet"
+ * from prose into a number that cannot move without somebody deciding it
+ * should. A surface leaving this list is the wave that covered it; a
+ * surface joining it is a regression, and either way the diff says so.
+ *
+ * The list is per RECIPE rather than per tool because a tool is not one
+ * classification: `brain_trigger operation=scan` names the pages it
+ * queued and `brain_trigger operation=terminal` does not.
+ */
+const STILL_NAMED_AT_REMOTE: ReadonlySet<string> = new Set([
+ "brain_agent_diff mode=browse",
+ "brain_agent_diff mode=diff",
+ "brain_agent_diff mode=map",
+ "brain_agent_query",
+ "brain_analytics view=belief_evolution",
+ "brain_analytics view=concept_synthesis",
+ "brain_analytics view=timeline",
+ "brain_anticipatory_context",
+ "brain_brief view=morning",
+ "brain_claims operation=at",
+ "brain_claims operation=current",
+ "brain_claims operation=history",
+ "brain_context",
+ "brain_context_pack",
+ "brain_design_note",
+ "brain_doctor",
+ "brain_doctor #1",
+ "brain_doctor #2",
+ "brain_event_trace",
+ "brain_idea_discovery",
+ "brain_pre_compress_pack",
+ "brain_retention",
+ "brain_scaffold_stub action=list",
+ "brain_stale_scan",
+ "brain_trigger operation=history",
+ "brain_trigger operation=list",
+ "brain_trigger operation=scan",
+ "brain_unlinked_mentions",
+]);
+
+/**
+ * How many recipes the fixture actually puts the reserved page in front
+ * of, at a reach that reaches it - MEASURED, not claimed.
+ *
+ * Without this, the `not.toContain` sweep below could be green because
+ * the fixture never reached the page on those recipes, and a reader
+ * counting green test names would read a per-tool proof into a clean
+ * sweep over an empty fixture. A named subset used to be the whole
+ * anchor; a review measured the gap and found it two orders of magnitude
+ * wider than the four recipes named, so the gap is a number this file
+ * takes rather than a caveat it writes.
+ *
+ * Both bounds are asserted. The floor is the non-vacuity claim; the
+ * ceiling is what stops the number drifting up unremarked, because a
+ * recipe joining the reaching set is a recipe whose remote half just
+ * became load-bearing and should be read as such in the diff.
+ */
+const RECIPES_REACHING_RESERVED_AT_LOCAL = { min: 25, max: 45 } as const;
+
+/** Recipes observed to reach it, accumulated as the sweep below runs. */
+let recipesReachingAtLocal = 0;
+/** Recipes the sweep actually drove, so a filtered run cannot read as a measurement. */
+let recipesMeasuredAtLocal = 0;
+
+test("every recipe still naming a reserved page belongs to a surface the registry excludes", () => {
+ const covered = [...STILL_NAMED_AT_REMOTE].filter((label) =>
+ COVERED_TOOLS.has(label.split(" ")[0] ?? label),
+ );
+ // A covered surface in this list would be the registry claiming a
+ // boundary this probe just watched it fail.
+ expect(covered.toSorted()).toEqual([]);
+});
+
+for (const entry of ALL_ENTRIES) {
+ for (const [index, recipe] of entry.calls.entries()) {
+ const label = probeLabel(entry.name, recipe, index);
+ const mustWithhold = COVERED_TOOLS.has(entry.name) || !STILL_NAMED_AT_REMOTE.has(label);
+ test(
+ `${label}: ${mustWithhold ? "names no reserved page at remote reach" : "still names one, and the registry says so"}`,
+ async () => {
+ const response = await drive(TRANSPORT_REACH.remote, entry.name, probeArgs(recipe));
+ if (mustWithhold) {
+ expect(response, `${label} at remote reach`).not.toContain(RESERVED_MARKER);
+ } else {
+ // The other direction of the equality: a recipe that stopped
+ // naming it has been covered, and this list has to say so.
+ expect(response, `${label} no longer names a reserved page`).toContain(RESERVED_MARKER);
+ }
+ // The reachability half, taken on this recipe's own fresh fixture
+ // and AFTER the assertion above, so the measurement cannot change
+ // what the sweep saw. Counted here rather than in a loop of its
+ // own because several recipes WRITE to the fixture, and a second
+ // pass over one vault would be measuring the vault they left.
+ const local = await drive(TRANSPORT_REACH.local, entry.name, probeArgs(recipe));
+ recipesMeasuredAtLocal += 1;
+ if (local.includes(RESERVED_MARKER)) recipesReachingAtLocal += 1;
+ },
+ PROBE_TIMEOUT_MS,
+ );
+ }
+}
+
+test("the sweep's non-vacuity is measured, not assumed", () => {
+ // The counter is only meaningful if the sweep above actually ran, so
+ // that is asserted first: under a name filter this fails by saying the
+ // sweep was skipped rather than by reporting a bound nobody measured.
+ const recipeCount = ALL_ENTRIES.reduce((n, entry) => n + entry.calls.length, 0);
+ expect(recipesMeasuredAtLocal, "the sweep did not run, so nothing was measured").toBe(
+ recipeCount,
+ );
+ expect(recipesReachingAtLocal).toBeGreaterThanOrEqual(RECIPES_REACHING_RESERVED_AT_LOCAL.min);
+ expect(recipesReachingAtLocal).toBeLessThanOrEqual(RECIPES_REACHING_RESERVED_AT_LOCAL.max);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The federated caller shape
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The union over several vaults is a different caller SHAPE, not a
+ * different rule - `searchAcrossVaults` spreads the caller's options onto
+ * every origin, so each leg carries the reach the transport minted. That
+ * is exactly the kind of claim that is true until someone adds an origin
+ * loop that rebuilds its options, so it is executed rather than asserted
+ * in a comment.
+ */
+test("a federated caller is bound by the same rule on every origin", async () => {
+ const external = join(tmp, "external-vault");
+ mkdirSync(join(external, "Brain"), { recursive: true });
+ mkdirSync(join(external, "notes"), { recursive: true });
+ writeFileSync(
+ join(external, "notes", `${RESERVED_MARKER}-external.md`),
+ `---\n${RESERVE_LINE}\n---\n\n${QUERY} ${PROBE_TERMS} external\n`,
+ );
+ writeFileSync(
+ join(external, "notes", "external-shared.md"),
+ `# External\n\n${QUERY} ${PROBE_TERMS} external shared\n`,
+ );
+ await indexVault(resolveSearchConfig({ vault: external, configPath }), { force: true });
+ addRecallSource(configPath, vault, "team", external);
+
+ const args = { query: QUERY, global: true, visibility: [REMOTE_DENY_VISIBILITY_TOKEN] };
+ // The union must reach the foreign origin at all, or the assertion
+ // below is clean because nothing federated.
+ const local = await drive(TRANSPORT_REACH.local, "brain_search", args);
+ expect(local).toContain("external-shared.md");
+ expect(local).toContain(RESERVED_MARKER);
+
+ expect(await drive(TRANSPORT_REACH.remote, "brain_search", args)).not.toContain(RESERVED_MARKER);
+});
+
+test("the _meta channel is live on these probes, so the sweep covers it", async () => {
+ // The refusal proves the member is populated. A sweep that asserted
+ // over an envelope with no `_meta` would be covering a channel that was
+ // never there.
+ //
+ // Asserted on the RESULT rather than by searching the serialised
+ // envelope for the string: every probe sends `params._meta.progressToken`
+ // itself, so a substring check matched the request the probe made and
+ // would have stayed green over an empty or absent `result._meta` - the
+ // exact retirement it exists to catch.
+ const response = await drive(TRANSPORT_REACH.remote, "brain_search", { query: QUERY });
+ const result = (JSON.parse(response) as { result?: Record<string, unknown> }).result;
+ const meta = result?.[PROGRESS_META_RESULT_MEMBER] as Record<string, unknown> | undefined;
+ expect(meta, "result._meta is where a reserved name could ride out").toBeDefined();
+ expect(Object.keys(meta!)).toContain(PROGRESS_META_KEY);
+});
diff --git a/tests/mcp/visibility-not-found-parity.test.ts b/tests/mcp/visibility-not-found-parity.test.ts
new file mode 100644
index 00000000..55d889cc
--- /dev/null
+++ b/tests/mcp/visibility-not-found-parity.test.ts
@@ -0,0 +1,338 @@
+/**
+ * Root C: a withheld read answers exactly as an absent one
+ * (private-is-not-a-suggestion, unit 5).
+ *
+ * The third root is the pair of primitives that take a caller-supplied
+ * KEY rather than a query: a chunk id (`expandHit`) and a Brain artifact
+ * id (the templated `osb://` resources). Both hand back a page's path,
+ * title and body, and neither ever consulted `visibility:`.
+ *
+ * What this file pins is not only that the page is withheld but that the
+ * REFUSAL is indistinguishable from the answer an absent key produces.
+ * A distinguishable refusal is an existence oracle over exactly the
+ * population the boundary exists to hide, and both key spaces are
+ * enumerable: a chunk id is a sequential integer, and a preference id is
+ * `pref-<topic-slug>`.
+ *
+ * The reachability half is not optional. A probe that never saw the
+ * marker at local reach would be a clean sweep over an empty fixture.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { appendLogEvent } from "../../src/core/brain/log.ts";
+import { brainDirs } from "../../src/core/brain/paths.ts";
+import { writePreference } from "../../src/core/brain/preference.ts";
+import { writeSignal } from "../../src/core/brain/signal.ts";
+import { BRAIN_LOG_EVENT_KIND, BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";
+import { TRANSPORT_REACH, type TransportReach } from "../../src/core/graph/transport-reach.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
+import { expandHit } from "../../src/core/search/cards.ts";
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { search } from "../../src/core/search/search.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import { readResource, type ResourceContext } from "../../src/mcp/resources.ts";
+import { BRAIN_TOOLS } from "../../src/mcp/brain-tools.ts";
+import { listRecallTelemetry } from "../../src/core/brain/recall-telemetry.ts";
+import type { ServerContext, ToolDefinition } from "../../src/mcp/tool-contract.ts";
+
+/** HOME is pinned per file by convention; nothing pins it globally. */
+process.env["HOME"] = mkdtempSync(join(tmpdir(), "o2b-vis-parity-home-"));
+
+/** Appears only inside artifacts carrying the reserved token. */
+const MARKER = "zzreservedmarkerzz";
+const LOG_DATE = "2026-05-04";
+const SHARED_TOPIC = "shared";
+/** The topic whose only rule is the reserved preference. */
+const RESERVED_TOPIC = `${MARKER}-topic`;
+const QUERY = "lattice widgets";
+
+let vault: string;
+let dbPath: string;
+
+beforeEach(async () => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-vis-parity-vault-"));
+ dbPath = join(mkdtempSync(join(tmpdir(), "o2b-vis-parity-db-")), "brain.sqlite");
+ for (const sub of ["preferences", "retired", "inbox", "log"]) {
+ mkdirSync(join(vault, "Brain", sub), { recursive: true });
+ }
+ makePref(SHARED_TOPIC);
+ makePref(`${MARKER}-r`, RESERVED_TOPIC);
+ reserve(`pref-${MARKER}-r`);
+ // The reserved preference links the shared one, so a backlinks read the
+ // caller IS entitled to fans out to a reserved source artifact.
+ const path = join(brainDirs(vault).preferences, `pref-${MARKER}-r.md`);
+ writeFileSync(path, `${readFileSync(path, "utf8")}\nSee [[pref-${SHARED_TOPIC}]].\n`);
+ appendLogEvent(
+ vault,
+ {
+ timestamp: `${LOG_DATE}T00:00:00Z`,
+ eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
+ body: {
+ path: `Brain/preferences/pref-${MARKER}-r.md`,
+ preference: `[[pref-${MARKER}-r]]`,
+ result: "applied",
+ },
+ },
+ { deviceId: "" },
+ );
+ // Two signals on the shared topic, one of them reserved: the topic
+ // read is entitled, so the reserved ROW has to disappear from it - and
+ // from the count the telemetry writes about it.
+ for (const [slug, reserved] of [
+ [`${SHARED_TOPIC}-open`, false],
+ [`${MARKER}-sig`, true],
+ ] as ReadonlyArray<readonly [string, boolean]>) {
+ const res = writeSignal(vault, {
+ topic: SHARED_TOPIC,
+ signal: "positive",
+ agent: "tester",
+ principle: `principle for ${slug}`,
+ created_at: "2026-05-01T00:00:00Z",
+ date: "2026-05-01",
+ slug,
+ });
+ if (reserved) reserveFile(res.path);
+ }
+ // A vault page for the chunk-id half, and an ordinary one beside it so
+ // the query has something to match either way.
+ writeFileSync(join(vault, "open.md"), `# Open\n\nshared ${QUERY} here`);
+ writeFileSync(
+ join(vault, `${MARKER}.md`),
+ `---\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]\n---\n# ${MARKER}\n\nclassified ${QUERY} here`,
+ );
+ await indexVault(makeConfig({ vault, dbPath }));
+});
+
+function makePref(slug: string, topic?: string): void {
+ writePreference(vault, {
+ slug,
+ topic: topic ?? slug,
+ principle: `principle for ${slug}`,
+ created_at: "2026-05-01T00:00:00Z",
+ unconfirmed_until: "2026-05-08T00:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
+ confirmed_at: "2026-05-02T00:00:00Z",
+ });
+}
+
+/** Add the reserved token to an existing preference's frontmatter. */
+function reserve(id: string): void {
+ reserveFile(join(brainDirs(vault).preferences, `${id}.md`));
+}
+
+/** Add the reserved token to the frontmatter of the page at `path`. */
+function reserveFile(path: string): void {
+ const text = readFileSync(path, "utf8");
+ const end = text.indexOf("\n---", 3);
+ if (end === -1) throw new Error(`no frontmatter block in ${path}`);
+ writeFileSync(
+ path,
+ `${text.slice(0, end)}\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]${text.slice(end)}`,
+ );
+}
+
+/** Read one resource at `reach`, folding a refusal into the answer. */
+function read(uri: string, reach: TransportReach): string {
+ const ctx: ResourceContext = { vault, reach };
+ try {
+ return readResource(ctx, uri).text;
+ } catch (err) {
+ return `threw: ${err instanceof Error ? err.message : String(err)}`;
+ }
+}
+
+/**
+ * Every templated resource that fans out to a reserved artifact from a
+ * key the caller IS entitled to name - the shape a caller cannot be
+ * refused for asking, so the page has to disappear from the answer
+ * instead.
+ */
+const FAN_OUT_URIS: ReadonlyArray<{ readonly uri: string; readonly why: string }> = [
+ { uri: `osb://backlinks/pref-${SHARED_TOPIC}`, why: "a backlink names its source artifact" },
+ { uri: `osb://log/${LOG_DATE}`, why: "a log event names the preference it was about" },
+];
+
+describe("templated osb:// resources", () => {
+ for (const { uri, why } of FAN_OUT_URIS) {
+ test(`${uri}: reaches the reserved artifact locally and withholds it remotely`, () => {
+ expect(read(uri, TRANSPORT_REACH.local), `${uri} local (${why})`).toContain(MARKER);
+ expect(read(uri, TRANSPORT_REACH.remote), `${uri} remote (${why})`).not.toContain(MARKER);
+ });
+ }
+
+ test("osb://topic renders the reserved rule locally and not remotely", () => {
+ // A topic whose only rule is reserved reads, at remote reach, as a
+ // topic with no rule - the shape the renderer already has for a topic
+ // that never reached promotion - rather than as a topic that refused.
+ const uri = `osb://topic/${RESERVED_TOPIC}`;
+ expect(read(uri, TRANSPORT_REACH.local)).toContain(`principle for ${MARKER}-r`);
+ expect(read(uri, TRANSPORT_REACH.remote)).not.toContain(`principle for ${MARKER}-r`);
+ });
+
+ test("osb://preference returns the page locally and none of it remotely", () => {
+ const local = read(`osb://preference/pref-${MARKER}-r`, TRANSPORT_REACH.local);
+ expect(local).toContain(`principle for ${MARKER}-r`);
+ const remote = read(`osb://preference/pref-${MARKER}-r`, TRANSPORT_REACH.remote);
+ expect(remote).not.toContain(`principle for ${MARKER}-r`);
+ });
+
+ test("a withheld preference is reported byte for byte as an absent one", () => {
+ const withheld = read(`osb://preference/pref-${MARKER}-r`, TRANSPORT_REACH.remote);
+ const absent = read("osb://preference/pref-never-existed", TRANSPORT_REACH.remote);
+ expect(withheld).toStartWith("threw:");
+ // The id each message echoes is the caller's own argument, so the
+ // comparison is made over the message with that argument removed.
+ expect(withheld.replace(`pref-${MARKER}-r`, "ID")).toBe(
+ absent.replace("pref-never-existed", "ID"),
+ );
+ });
+
+ test("the BARE SLUG key shape has the same parity as the prefixed one", () => {
+ // The reader accepts `pref-foo`, `ret-foo` and the bare slug, so the
+ // key space a caller enumerates is the bare one too. The absent
+ // branch echoes the NORMALISED id (`queryByPreference` was handed
+ // it); the withheld branch echoed the raw one, so the presence of the
+ // `pref-` prefix in the message answered "does this page exist" over
+ // exactly the reserved population.
+ const withheld = read(`osb://preference/${MARKER}-r`, TRANSPORT_REACH.remote);
+ const absent = read("osb://preference/never-existed", TRANSPORT_REACH.remote);
+ expect(withheld).toStartWith("threw:");
+ expect(withheld.replace(`pref-${MARKER}-r`, "ID")).toBe(
+ absent.replace("pref-never-existed", "ID"),
+ );
+ });
+});
+
+/**
+ * `brain_query mode=preference` over the same key space, through the tool
+ * rather than the resource. Preference ids are `pref-<slug>` and a slug
+ * is a topic name, so this is the most guessable key surface the boundary
+ * has.
+ */
+describe("brain_query mode=preference", () => {
+ const brainQuery = (): ToolDefinition => BRAIN_TOOLS.find((t) => t.name === "brain_query")!;
+
+ const ask = async (preference: string, reach: TransportReach): Promise<string> => {
+ const ctx: ServerContext = { vault, reach, configPath: null, repoRoot: null };
+ try {
+ await brainQuery().handler(ctx, { preference });
+ return "returned";
+ } catch (err) {
+ return `threw: ${err instanceof Error ? err.message : String(err)}`;
+ }
+ };
+
+ test("a withheld preference is refused with the message an absent one produces", async () => {
+ const withheld = await ask(`pref-${MARKER}-r`, TRANSPORT_REACH.remote);
+ const absent = await ask("pref-never-existed", TRANSPORT_REACH.remote);
+ expect(withheld).toStartWith("threw:");
+ // Only the caller's own argument may differ between the two.
+ expect(withheld.replace(`pref-${MARKER}-r`, "ID")).toBe(
+ absent.replace("pref-never-existed", "ID"),
+ );
+ });
+
+ test("the same preference is returned at local reach", async () => {
+ expect(await ask(`pref-${MARKER}-r`, TRANSPORT_REACH.local)).toBe("returned");
+ });
+
+ test("topic-mode telemetry counts the rows the caller was SHOWN", async () => {
+ // The count is written to the vault's recall-telemetry log and handed
+ // back verbatim by `brain_recall_telemetry`, so a pre-filter number
+ // is a count oracle reached through a second tool. The `since` branch
+ // recounted after filtering; the topic branch did not.
+ const ctx: ServerContext = {
+ vault,
+ reach: TRANSPORT_REACH.remote,
+ configPath: null,
+ repoRoot: null,
+ };
+ const out = (await brainQuery().handler(ctx, {
+ topic: SHARED_TOPIC,
+ telemetry: true,
+ })) as { signals: unknown[]; all_log_events: unknown[] };
+ const shown = out.signals.length + out.all_log_events.length;
+ const records = listRecallTelemetry(vault, { mode: "query" });
+ expect(records.length).toBeGreaterThan(0);
+ expect(records.at(-1)!.payload["result_count"]).toBe(shown);
+ });
+
+ test("that topic really does have a row to withhold, so the count above is not trivially equal", async () => {
+ const rows = async (reach: TransportReach): Promise<number> => {
+ const ctx: ServerContext = { vault, reach, configPath: null, repoRoot: null };
+ const out = (await brainQuery().handler(ctx, { topic: SHARED_TOPIC })) as {
+ signals: unknown[];
+ all_log_events: unknown[];
+ };
+ return out.signals.length + out.all_log_events.length;
+ };
+ expect(await rows(TRANSPORT_REACH.local)).toBeGreaterThan(await rows(TRANSPORT_REACH.remote));
+ });
+});
+
+describe("the by-chunk-id drill-down", () => {
+ async function reservedChunkId(): Promise<number> {
+ const outcome = await search(makeConfig({ vault, dbPath }), {
+ query: QUERY,
+ limit: 20,
+ // The page declares a visibility token, so the caller's own scope
+ // has to name it before the reach question is even reached.
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ transportReach: TRANSPORT_REACH.local,
+ });
+ const hit = outcome.results.find((r) => r.path === `${MARKER}.md`);
+ if (hit === undefined) throw new Error("the reserved page was not indexed");
+ return hit.chunkId;
+ }
+
+ test("hydrates the reserved page at local reach", async () => {
+ const result = await expandHit(makeConfig({ vault, dbPath }), {
+ chunkId: await reservedChunkId(),
+ transportReach: TRANSPORT_REACH.local,
+ });
+ expect(result.note.path).toBe(`${MARKER}.md`);
+ });
+
+ test("refuses it at remote reach with the absent-chunk message", async () => {
+ const chunkId = await reservedChunkId();
+ const refused = await expandHit(makeConfig({ vault, dbPath }), {
+ chunkId,
+ transportReach: TRANSPORT_REACH.remote,
+ }).then(
+ () => null,
+ (e: unknown) => (e as Error).message,
+ );
+ // The absent id is a chunk id no document can have, so the two
+ // messages differ only in the caller's own argument.
+ const absent = await expandHit(makeConfig({ vault, dbPath }), {
+ chunkId: Number.MAX_SAFE_INTEGER,
+ transportReach: TRANSPORT_REACH.remote,
+ }).then(
+ () => null,
+ (e: unknown) => (e as Error).message,
+ );
+ expect(refused).not.toBeNull();
+ expect(refused).toBe(`chunk not found: ${chunkId}`);
+ expect(absent).toBe(`chunk not found: ${Number.MAX_SAFE_INTEGER}`);
+ });
+
+ test("still hydrates an ordinary page at remote reach", async () => {
+ const outcome = await search(makeConfig({ vault, dbPath }), {
+ query: QUERY,
+ limit: 20,
+ transportReach: TRANSPORT_REACH.remote,
+ });
+ const hit = outcome.results.find((r) => r.path === "open.md");
+ if (hit === undefined) throw new Error("the ordinary page was not indexed");
+ const result = await expandHit(makeConfig({ vault, dbPath }), {
+ chunkId: hit.chunkId,
+ transportReach: TRANSPORT_REACH.remote,
+ });
+ expect(result.note.path).toBe("open.md");
+ });
+});
diff --git a/tests/mcp/visibility-scope.test.ts b/tests/mcp/visibility-scope.test.ts
index 10b932ec..d97a5f10 100644
--- a/tests/mcp/visibility-scope.test.ts
+++ b/tests/mcp/visibility-scope.test.ts
@@ -11,10 +11,16 @@ import { join } from "node:path";
import { SEARCH_TOOLS } from "../../src/mcp/search-tools.ts";
import { indexVault, resolveSearchConfig } from "../../src/core/search/index.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
+import type { ServerContext } from "../../src/mcp/tool-contract.ts";
let vault: string;
let configHome: string;
-let ctx: { vault: string; configPath: string };
+/** A caller this server established nothing about: the narrowest reach. */
+let ctx: ServerContext;
+/** The same caller, arriving on a transport that proved local access. */
+let localCtx: ServerContext;
beforeEach(async () => {
vault = mkdtempSync(join(tmpdir(), "o2b-vis-vault-"));
@@ -30,7 +36,8 @@ beforeEach(async () => {
join(vault, "notes", "secret.md"),
"---\nvisibility: [private]\n---\n# Secret\n\nclassified lattice notes about widgets",
);
- ctx = { vault, configPath };
+ ctx = { vault, configPath, repoRoot: null };
+ localCtx = { ...ctx, reach: TRANSPORT_REACH.local };
const config = resolveSearchConfig({ vault, configPath });
await indexVault(config, {});
});
@@ -44,31 +51,42 @@ function paths(out: { results: Array<{ path: string }> }): string[] {
return out.results.map((r) => r.path).toSorted();
}
+function brainSearch(): (typeof SEARCH_TOOLS)[number] {
+ const tool = SEARCH_TOOLS.find((t) => t.name === "brain_search");
+ if (tool === undefined) throw new Error("brain_search is not in SEARCH_TOOLS");
+ return tool;
+}
+
describe("brain_search visibility scope", () => {
test("a private page is hidden by default", async () => {
- const tool = SEARCH_TOOLS.find((t) => t.name === "brain_search")!;
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- const out = (await tool.handler(ctx as any, { query: "lattice widgets" })) as {
+ const out = (await brainSearch().handler(ctx, { query: "lattice widgets" })) as {
results: Array<{ path: string }>;
};
expect(paths(out)).toEqual(["notes/public.md"]);
});
- test("the private page appears when its visibility is requested", async () => {
- const tool = SEARCH_TOOLS.find((t) => t.name === "brain_search")!;
- const out = (await tool.handler(
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- ctx as any,
- { query: "lattice widgets", visibility: ["private"] },
- )) as { results: Array<{ path: string }> };
+ test("the private page appears when its visibility is requested at local reach", async () => {
+ const out = (await brainSearch().handler(localCtx, {
+ query: "lattice widgets",
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ })) as { results: Array<{ path: string }> };
expect(paths(out)).toEqual(["notes/public.md", "notes/secret.md"]);
});
+ test("the same request at remote reach gets nothing back", async () => {
+ // The caller argument narrows and cannot lift: asking for the
+ // reserved scope over a transport that established nothing is
+ // answered exactly as the default scope is.
+ const out = (await brainSearch().handler(ctx, {
+ query: "lattice widgets",
+ visibility: [REMOTE_DENY_VISIBILITY_TOKEN],
+ })) as { results: Array<{ path: string }> };
+ expect(paths(out)).toEqual(["notes/public.md"]);
+ });
+
test("a non-array visibility argument is rejected", async () => {
- const tool = SEARCH_TOOLS.find((t) => t.name === "brain_search")!;
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
await expect(
- tool.handler(ctx as any, { query: "lattice", visibility: "private" }),
+ brainSearch().handler(ctx, { query: "lattice", visibility: "private" }),
).rejects.toThrow(/visibility/);
});
});
diff --git a/tests/openclaw/page-search-visibility.test.ts b/tests/openclaw/page-search-visibility.test.ts
new file mode 100644
index 00000000..0030e6aa
--- /dev/null
+++ b/tests/openclaw/page-search-visibility.test.ts
@@ -0,0 +1,95 @@
+/**
+ * The OpenClaw page walker is inside the boundary
+ * (private-is-not-a-suggestion, unit 4).
+ *
+ * `tests/core/architecture/visibility-surface-census.test.ts` named this
+ * surface as an un-swept page search, and it was: `second_brain_query`
+ * listed pages filtered by entity status alone. It is a tool a model
+ * calls, not a command an operator types, so it adopts the narrowest
+ * reach - see `OPENCLAW_TRANSPORT_REACH`.
+ *
+ * The aggregate is asserted alongside the listing, because a count that
+ * still included the withheld page would be an existence oracle: it would
+ * answer "there is one more page here than I am showing you".
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
+
+/** The plugin SDK is an external at build time and absent at test time. */
+mock.module("openclaw/plugin-sdk/plugin-entry", () => ({
+ definePluginEntry: (entry: unknown) => entry,
+}));
+
+interface RegisteredTool {
+ readonly name: string;
+ execute(id: string, params: Record<string, unknown>): Promise<unknown>;
+}
+
+interface PageSearchResult {
+ readonly total_pages: number;
+ readonly returned: number;
+ readonly pages: ReadonlyArray<{ readonly title: string; readonly path: string }>;
+}
+
+/** The listing tool's registered name, as the census knows it. */
+const PAGE_SEARCH_TOOL = "second_brain_query";
+
+/** A marker present only in the reserved page, in every field it has. */
+const RESERVED_MARKER = "zzreservedmarkerzz";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "openclaw-vis-"));
+ writeFileSync(join(vault, "open.md"), "---\ntitle: Open page\n---\n\nordinary body");
+ writeFileSync(
+ join(vault, `${RESERVED_MARKER}.md`),
+ `---\ntitle: ${RESERVED_MARKER}\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]\n---\n\n${RESERVED_MARKER} body`,
+ );
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+async function pageSearch(params: Record<string, unknown>): Promise<PageSearchResult> {
+ const tools: RegisteredTool[] = [];
+ const entry = (await import("../../src/openclaw/index.ts")).default as {
+ register(api: unknown): void;
+ };
+ entry.register({
+ pluginConfig: { vault },
+ on: () => undefined,
+ registerTool: (tool: RegisteredTool) => tools.push(tool),
+ });
+ const tool = tools.find((t) => t.name === PAGE_SEARCH_TOOL);
+ if (tool === undefined) throw new Error(`${PAGE_SEARCH_TOOL} was not registered`);
+ const out = (await tool.execute("1", params)) as {
+ content: ReadonlyArray<{ readonly text: string }>;
+ };
+ const text = out.content[0]?.text;
+ if (text === undefined) throw new Error(`${PAGE_SEARCH_TOOL} returned no text content`);
+ return JSON.parse(text) as PageSearchResult;
+}
+
+describe(PAGE_SEARCH_TOOL, () => {
+ test("does not list a page carrying the reserved token", async () => {
+ const result = await pageSearch({});
+ expect(result.pages.map((p) => p.title)).toEqual(["Open page"]);
+ expect(JSON.stringify(result)).not.toContain(RESERVED_MARKER);
+ });
+
+ test("does not count it either, so the aggregate is not an existence oracle", async () => {
+ const result = await pageSearch({});
+ expect(result.total_pages).toBe(1);
+ expect(result.returned).toBe(1);
+ });
+
+ test("a title pattern naming it matches nothing", async () => {
+ const result = await pageSearch({ pattern: RESERVED_MARKER });
+ expect(result.pages).toEqual([]);
+ expect(result.returned).toBe(0);
+ });
+});