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
79.3 KB
Raw Blame
/**
 * Every surface that can hand a vault note's path, title, or body back to
 * 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:` 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/`, `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.
 *
 * 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 read root decides what a surface may hand back. */
export const VISIBILITY_SURFACE_CATEGORY = Object.freeze({
  /**
   * 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",
} as const);

export type VisibilitySurfaceCategory =
  (typeof VISIBILITY_SURFACE_CATEGORY)[keyof typeof VISIBILITY_SURFACE_CATEGORY];

/** Which interface a surface is reached through. */
export const VISIBILITY_SURFACE_KIND = Object.freeze({
  mcpTool: "mcp_tool",
  cliVerb: "cli_verb",
  mcpResource: "mcp_resource",
  /** A structural fact about the index's own storage, not a callable surface. */
  indexStore: "index_store",
} as const);

export type VisibilitySurfaceKind =
  (typeof VISIBILITY_SURFACE_KIND)[keyof typeof VISIBILITY_SURFACE_KIND];

export interface VisibilitySurfaceEntry {
  /** The tool name, `<group> <verb>` CLI path, resource URI, or fixed label. */
  readonly surface: string;
  readonly kind: VisibilitySurfaceKind;
  readonly category: VisibilitySurfaceCategory;
  /** What the category alone does not say - the source-verified argument. */
  readonly reason: string;
}

const K = VISIBILITY_SURFACE_KIND;
const C = VISIBILITY_SURFACE_CATEGORY;

/**
 * The population, hand-verified against source (main clone at
 * `feat/nothing-writes-silently`, HEAD `31561384` and after). The census
 * test's mechanical sweep is the check that this list has not gone
 * stale; the reasons below are what that sweep cannot itself produce.
 */
export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry> = Object.freeze([
  // --- Covered: reaches search()'s pool-filters pipeline -------------------
  {
    surface: "brain_search",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "calls core/search/search.ts's search() directly, which runs assembleRankedResults -> " +
      "applyPoolFilters -> applyVisibilityScope (pool-filters.ts:130) on every result before " +
      "returning it, unconditionally - the empty-scope-hides-tagged-pages rule applies even when " +
      "the caller passes no visibility argument at all. A zero-result answer below local " +
      "reach carries no coverage receipt and no index count: a not_found names the index time " +
      "only and an unknown states the fixed reason of its unknown_reason " +
      "(corpusVerdictAtReach in pipeline/outcome.ts, withoutCorpusCounts). Its root coverage " +
      "answers at the caller's reach: below local reach an authorized note root counts as " +
      "reached only through a page that caller may read (probeRetrievalCorpus threads the " +
      "reach into indexRootCoverage's admit predicate), so a root holding nothing else answers " +
      "like an empty one. Its ranking statistics are a stated residual: the bm25 corpus " +
      "statistics and the diversity rerank are computed over the shared index, which counts " +
      "pages the caller may not read (reserved pages, the Brain log), so two vaults that " +
      "return the same paths remotely can return different scores and rerank reasons - a weak " +
      "count signal across the whole index, not a page or its content. Delivery shaping " +
      "(delivery-trust, lane A): every delivered row's content is fenced at remote reach " +
      "through the shared delivery shaper (cached page-provenance probe plus the " +
      "untrusted-source fence), byte-identical at local reach; a withheld row gains no fence " +
      "and no count.",
  },
  {
    surface: "brain_file_context",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "src/mcp/search-tools.ts's toolBrainFileContext calls fileContextRecall " +
      "(core/brain/file-recall.ts), which calls search() with the derived query and no visibility " +
      "override, so it inherits the same pool-filters gate as brain_search. It is covered " +
      "transitively, not by an independent check of its own. Delivery shaping (delivery-trust, " +
      "lane A): the tool delivers path, title and score only - no stored text crosses this " +
      "surface at any reach, so there is nothing to fence (quote-fencing-search.test.ts pins " +
      "the exact key set).",
  },
  {
    surface: "search query",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "src/cli/search/verbs/query.ts calls search() with the CLI's --visibility flag threaded " +
      "through, the same function and the same pool-filters gate brain_search uses.",
  },

  // --- Excluded: MCP tools ---------------------------------------------------
  {
    surface: "brain_search_expand",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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. Delivery shaping (delivery-trust, " +
      "lane A): the hydrated chunk text is fenced at remote reach through the same shaper, " +
      "byte-identical at local reach.",
  },
  {
    surface: "second_brain_query",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "packContext() (core/brain/context-pack.ts) draws candidates only from Brain/preferences " +
      "and Brain/retired via collectPreferencePages, and the MCP tool hands packContext a " +
      "reachView predicate that drops a reserved candidate before ranking and budgeting - so a " +
      "page tagged visibility: private contributes nothing to items, lanes, skipped, warnings, " +
      "deduped_from or the receipt at remote reach (t_sec_pack_reach). It stays " +
      "EXCLUDED because the slice also injects the bodies of pages that ARE readable, and a " +
      "readable hub page's body can name a reserved page in a wikilink - second-hand text no " +
      "per-page gate can rewrite, which is true of every content-returning surface and is why " +
      "`search check` still reports this surface to operators.",
  },
  {
    surface: "brain_query",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "queryByPreference / queryByRuleTopic (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. Delivery shaping (delivery-trust, lane " +
      "A): the preference and topic payload bodies are fenced at remote reach through the " +
      "shared delivery binding (one reach resolution and one frontmatter cache per request), " +
      "byte-identical at local reach; the log-entry serializers are the stated boundary and " +
      "stay untouched.",
  },
  {
    surface: "brain_backlinks",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "findUnlinkedMentions (core/brain/link-graph/unlinked-mentions.ts) walks Brain/preferences " +
      "and Brain/retired itself, so the MCP handler passes reachView alongside the owner scope: " +
      "a reserved SOURCE is skipped before its body is read, and a reserved TARGET answers with " +
      "no mentions - the reply an absent target gets - because each mention's `term` is the " +
      "target's title or alias. Each mention's `context` is one line of the source page's own " +
      "prose, so it shapes through the request's delivery binding at the page the source id was " +
      "parsed from.",
  },
  {
    surface: "brain_sources",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "aggregateSources (core/brain/portability/sources.ts) reads Brain's own signal registry " +
      "under readdirSync, with no visibility check - the field is not part of a signal's schema " +
      "and the reader never looks at a general vault page.",
  },
  {
    // The four source-ingest-suite tools joined the swept population when
    // ingest-tools.ts began reading page frontmatter for the archive-orphan
    // decision (answer trust), which made the whole file a note-content
    // importer under the census's file-level rule. All four were already
    // asking a read root at their read sites; the rows below are that fact
    // written down per surface, not a behavior change.
    surface: "brain_ingest_source",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the handler hands the ingest `readable: readableAtContextReach(ctx)` " +
      "(ingest-tools.ts), so a summary page the caller may not read at its reach " +
      "answers exactly as an absent one - never staged, never named in the " +
      "result, and the review-queue disposition is decided for the credential-" +
      "minted subject rather than the caller-named agent.",
  },
  {
    surface: "brain_search_by_source",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "every hit is filtered through the same `readable(entry.path)` predicate " +
      "before serialization, then through `isPathOwnerVisible` under the caller's " +
      "owner scope with a fail-closed frontmatter parse, and `total` counts only " +
      "what is returned, so a hidden page contributes neither an entry nor a count.",
  },
  {
    surface: "brain_delete_by_source",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the plan is built with `include: readableAtContextReach(ctx)`, so an " +
      "original or derived page the caller may not read at its reach is planned " +
      "and deleted exactly as an absent one - never confirmed, never named in " +
      "match_list, never removed; the archive-orphan decision reads only stamps " +
      "on pages this same run is already deleting.",
  },
  {
    surface: "brain_ingest_batch_plan",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "`planBatches` and its reconcile pass take the same " +
      "`readableAtContextReach(ctx)` predicate, so a source file the caller may " +
      "not read at its reach is planned as an absent one - not batched, not " +
      "counted, and not named in any batch's file list.",
  },
  {
    surface: "brain_audit",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "readPrefAudit (core/brain/pref-audit.ts) returns preference-mutation ledger records - " +
      "timestamp, pref_id, op, agent, revision hashes - never a note body or title, and no " +
      "visibility check runs over them. Included for completeness though its disclosure is " +
      "narrower than the other entries here: no page content crosses this surface at all.",
  },
  {
    // Delivery trust (lane D). The attestation store sits under
    // `.open-second-brain/`, so the sweep has no frontmatter to read at
    // this file; the row is the fact written down rather than a behavior
    // change.
    surface: "brain_attestations",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "list and verify (src/mcp/brain/attest-tools.ts) read the signed attestation records " +
      "under .open-second-brain/attestations/ and re-measure the Brain log against the newest " +
      "one - the rows carry attestation ids, timestamps, device ids, shard names, hashes and " +
      "verdicts, never a note path, title or body, so the withheld-row refusals of the content " +
      "tools have nothing to refuse here and the answer is identical at every reach. Included " +
      "for completeness of the file-level sweep only.",
  },
  {
    surface: "brain_bridges",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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.covered,
    reason:
      "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",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "auditMoc (core/brain/link-graph/moc-audit.ts) classifies a hub's outbound links through " +
      "buildBacklinkIndex, the same ownerScopeView-only, visibility-blind path brain_backlinks " +
      "uses.",
  },
  {
    surface: "brain_deep_synthesis",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "discoverIdeas (core/brain/idea-discovery.ts) takes the handler's " +
      "readableAtContextReach(ctx) as its include option and leaves a page the caller may not " +
      "read at its reach out of the inbound-link walk and the candidates, before ranking and " +
      "the cap, so a withheld research page is answered as an absent one.",
  },
  {
    surface: "brain_dead_ends",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "list keeps only the entries and parse warnings whose page readableAtContextReach(ctx) " +
      "keeps, so a withheld dead end is absent from the answer; record writes the caller's own " +
      "dead end and, below local reach, leaves out the ids the overflow trim archived. The trim " +
      "still counts every active dead end against the cap but, handed the same predicate, " +
      "archives only the readable ones, so a withheld dead end is never moved; a same-day id " +
      "collision with a withheld dead end still takes a suffix (inherent create-collision " +
      "residual).",
  },
  {
    surface: "brain_claims",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "toolBrainClaims's own docblock (knowledge-tools.ts) states a claim row carries the " +
      "artifact's id, vault-relative path, topic and full principle text; every row-returning " +
      "operation and the rebuild count keep a row only when it passes gatedOwnerScopeView and, " +
      "at the caller's reach, reachView over its page, its id under the pref- and ret- " +
      "spellings, and the records that superseded or contest it. The principle is the record's " +
      "own stored text, so it shapes through the request's delivery binding at the claim's own " +
      "page - the same text brain_query fences inside the preference payloads.",
  },
  {
    surface: "brain_truth",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "the entity claim ledger (core/brain/truth/*) returns claim values, provenance wikilinks " +
      "and cross-agent collision records keyed by entity, with no visibility check anywhere in " +
      "ingest, slots, conflicts, aggregate or collisions.",
  },
  {
    surface: "brain_labels",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "show and suggest ask reachView; assign and remove resolve the page through " +
      "resolveNotePath with readableAtContextReach(ctx), so a page the caller may not read is " +
      "refused with 'note does not exist' before its frontmatter is read or written.",
  },
  {
    surface: "brain_tiers",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "check keeps only the drift rows whose page passes the handler's " +
      "readableAtContextReach(ctx), and restore and accept refuse any other page with the 'not " +
      "indexed' error a page the index never saw gets, before the drift is read or anything is " +
      "written.",
  },
  {
    surface: "brain_doctor",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the read-only report keeps every issue stream through the owner view ANDed with " +
      "reachView, over the doctorIssueRefs each issue names (path, target, sources, message " +
      "wikilinks), takes ok and trust_verdict again over the kept issues, and below local reach " +
      "recounts the tier-drift warning over the rows readableAtContextReach(ctx) keeps. The " +
      "doctor pass is handed the same predicate, so the counts its checks take before any " +
      "issue is filtered answer at the caller's reach too: a withheld page spends no slot of " +
      "the removed-tool warning cap or of the per-code uncertain cap, is neither a state nor a " +
      "consumer in the stale-dependency audit, and adds no principle, topic or preference to " +
      "the semantic-health detectors behind the concept-gap and contradiction warnings, and a " +
      "withheld vault-root instruction file raises no ceiling warning. The " +
      "repair branch hands applyRepair the caller's reach, which bounds the findings before the " +
      "plan is derived, and the same predicate, so the checks behind the plan count and cap " +
      "over readable pages too: a withheld record is neither planned, counted nor written, and " +
      "the unfixable counts are those of a vault without it.",
  },
  {
    surface: "schema_inspect",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the lint and orphans views keep only the findings whose named pages (path, or the source " +
      "and target of a blocked link) pass reachView, and below local reach stats counts the same " +
      "kept findings; graph, explain_type, active_pack and packs read the schema pack and its " +
      "token usage counts, never a page path, title or body. Swept in through schema-admin.ts.",
  },
  {
    surface: "schema_apply_mutations",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "swept in for file-level completeness because schema-tools.ts also registers " +
      "schema_inspect: it writes Brain/_brain.yaml and returns the resulting pack, its diff and " +
      "the audit path, never a note path, title, or body.",
  },
  {
    surface: "brain_health",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "runs runDoctor's semantic-health pass handed readableAtContextReach(ctx), so the " +
      "detectors read only the preferences and signals the caller may read: concept_gaps (a " +
      "term and its frequency over principle text, which no reference view can judge) and the " +
      "suppressed counts are taken over those principles and topics, and a withheld preference " +
      "joins no contradiction, stale claim or batch. Each finding naming preferences by id is " +
      "then kept only when every member passes the gated owner view ANDed with reachView, and " +
      "the verdict is folded again over the kept families.",
  },
  {
    surface: "brain_status",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "its hygiene count asks the owner view ANDed with reachView and its cited pages answer " +
      "readableAtContextReach(ctx), but the doctor error and warning counts and the preference " +
      "counts are taken over the whole Brain layer, so they move with a reserved record " +
      "(a stated, deferred residual: no count is recomputed per reader yet); it returns counts " +
      "and problem labels, never a note path, title, or body.",
  },
  {
    surface: "brain_maintenance",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "below local reach run is refused with a fixed sentence (MAINTENANCE_RUN_LOCAL_ONLY) " +
      "before the lease or any write, because it runs the dream pass, the reindex, the bridges " +
      "and clusters lanes and custom tasks over the whole vault; status returns the lease and " +
      "journal only.",
  },
  {
    surface: "brain_secrets",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "swept into population because admin-policy-tools.ts, which admin-tools.ts (its home file) " +
      "imports, also imports parseFrontmatter " +
      "and Store for brain_labels/brain_tiers/brain_maintenance beside it - the handler itself " +
      "returns only secret names and run results, never a note path, title, or body. Listed for " +
      "completeness of the file-level population rule rather than as a real disclosure.",
  },
  {
    surface: "brain_artifact_get",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "a generic preview-artifact cache read (src/mcp/tools.ts's toolArtifactGet): it returns " +
      "whatever string another tool call stored under artifact_id when its own response was " +
      "preview-truncated, with no check of its own. When the truncated response came from a " +
      "note-returning excluded tool, the cached payload is that same unfiltered content.",
  },
  {
    surface: "brain_diarize",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "diarize() is handed readableAtContextReach(ctx): a subject page the caller may not read " +
      "answers as an unknown entity, an ingested-source page the caller may not read is neither " +
      "evidence, counted nor named in document_set, and the link candidates are filtered by the " +
      "same predicate beside the owner scope.",
  },
  {
    surface: "brain_context",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "toolBrainContext (context-tools.ts) serves Brain/active.md's bytes only to a local " +
      "reader with no owner scope enforced; any other reader gets renderActiveForReader's " +
      "in-memory render without the preference and retired records readableAtContextReach(ctx) " +
      "withholds, counts included, so the choice never depends on what is withheld. Delivery " +
      "shaping (delivery-trust, lane A): the active body and the pinned scratchpad body are " +
      "fenced at remote reach through the shared delivery shaper, byte-identical at local " +
      "reach; the constitution and scoped-rules blocks are the operator's own voice and stay " +
      "outside the fence.",
  },
  {
    surface: "brain_agent_query",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "queryAgentSources (core/brain/agent-source/query.ts) takes the handler's " +
      "reachView(ctx.vault, contextReach(ctx)) as its view option and drops, before the roster " +
      "is folded, every contribution whose named page or event-body string the caller may not " +
      "read at its reach, so a note-write row for a withheld page is answered as one for an " +
      "absent page; agent_scope still gates ownership. Delivery shaping (delivery-trust, lane " +
      "A): note-write contribution bodies (and the principle their data block echoes) are " +
      "fenced at remote reach through the shared delivery binding, byte-identical at local " +
      "reach; log rows are the stated boundary and stay untouched.",
  },
  {
    surface: "brain_writes",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "listNoteWrites / planNoteRevert (core/brain/notes/) project `note-write` events out of " +
      "the Brain log and never open the notes they name, so the MCP handler asks reachView over " +
      "every row's target before counting: at remote reach a write to a reserved page - or to " +
      "a file that can no longer be read, which fails closed - is dropped from both `list` and " +
      "`plan_revert`, and `total_matched` counts only what the caller may see.",
  },
  {
    surface: "brain_write_destinations",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "toolBrainWriteDestinations (query-tools.ts) folds the write ledger into per-destination " +
      "rows and asks reachView(ctx.vault, contextReach(ctx)) over every row's target before " +
      "counting, exactly as brain_writes does: at remote reach a destination whose page is " +
      "reserved against remote reads - or whose file can no longer be read, which fails " +
      "closed - is dropped from the rows and from total_matched, so a withheld page moves no " +
      "count. The coverage note states the derived-site gap rather than implying completeness.",
  },
  {
    surface: "brain_agent_diff",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "diffAgentSources folds queryAgentSources, and the handler passes the same " +
      "reachView(ctx.vault, contextReach(ctx)) view brain_agent_query does, so a contribution " +
      "naming a page the caller may not read at its reach is dropped before any count or topic " +
      "map is built; ownership is gated by the GATED server identity. Delivery shaping " +
      "(delivery-trust, lane A): contribution bodies are fenced at remote reach through the " +
      "same shared delivery binding, byte-identical at local reach.",
  },
  {
    surface: "brain_anticipatory_context",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "below local reach the handler builds the bundle for the caller with the same reachView " +
      "candidate filter brain_context_pack hands packContext, asked before ranking and " +
      "budgeting; it neither reads nor writes the shared per-root cache entry, so a bundle " +
      "cached for the operator is never served to a remote caller and a filtered bundle never " +
      "replaces the operator's, and it answers cache_state miss. Session hits follow the " +
      "session tools' <private> region model, a stated residual. Local reach is byte-identical. " +
      "It stays EXCLUDED for the reason brain_context_pack does: the bundle carries the bodies " +
      "of readable pages, and a readable page's body can name a reserved page in a wikilink.",
  },
  {
    surface: "brain_context_receipts",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "show returns a stored receipt's payload - the same content a prior brain_context_pack " +
      "call recorded - with no visibility re-check at read time; only a receipt-level " +
      "private/redacted flag applies, which is a different axis. Below local reach a " +
      "SessionStart injection receipt (pack-tools.ts receiptAtReach) drops the standing-rules " +
      "and scoped-rules items and source references and every figure that counts or measures " +
      "them (item_count, final_text_hash, final_text_chars, total_bytes, total_tokens, " +
      "scoped_rules_chars, budgeted_source_count), drops the budget block when no budgeted body " +
      "is left, and summary folds without the rule items, so a degraded injection that kept " +
      "only the rules counts as an empty receipt. A measured injection receipt whose every item " +
      "was a rule block (isRuleOnlyInjection) is withheld whole: list and summary exclude it " +
      "before their limit and fold bound, and show answers it as an unknown id. The show " +
      "payload also carries the session's reply-presence join (lookupReceiptReplyPresence, " +
      "context-receipts.ts), and that join runs at the caller's reach: a per-note row naming a " +
      "path the caller's reach view cannot read is withheld from per_note and counted in " +
      "withheld - absent when nothing was withheld - so a reserved page's path, line range and " +
      "verdict never reach a caller the page withheld itself from, and a filtered join cannot " +
      "read as a session that checked fewer notes.",
  },
  {
    surface: "brain_event_trace",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "resolveLogEventTraces (core/brain/event-trace.ts) takes the handler's " +
      "reachView(ctx.vault, contextReach(ctx)) as its view option and drops, before the limit " +
      "and the totals, every event whose artifacts or body strings name a page the caller may " +
      "not read at its reach, and every attached trace whose handoff reference it hides; a " +
      "dream shared with a withheld record is kept with its readable transitions only " +
      "(log-events-at-reach.ts), its body and artifacts read from that form, so the count " +
      "does not fall when a reserved preference shares a dream; each record id is judged " +
      "under its pref- and ret- spellings.",
  },
  {
    surface: "brain_foresight",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "assembles recurring routines, open commitments and open questions from Brain's own " +
      "recurrence/obligation/question stores - Brain-authored records, not general vault notes - " +
      "with no visibility check.",
  },
  {
    surface: "brain_pinned_context",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "reads/writes Brain/pinned.md, a single Brain-authored scratchpad file, with no visibility " +
      "check - the field would be meaningless on a file with exactly one owner-less instance. " +
      "Delivery shaping (delivery-trust, lane A): a READ of the scratchpad still fences the " +
      "body at remote reach through the shared delivery shaper (byte-identical at local, and " +
      "write acknowledgements stay byte-stable) - no visibility row, but no unfenced delivery " +
      "either.",
  },
  {
    surface: "brain_write_session",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "dispatchSubmit / listWriteSessions / readWriteSession (core/brain/write-session/*) read " +
      "and mutate staged write-session records - Brain's own queue, not general vault notes - " +
      "with no visibility check.",
  },
  {
    surface: "brain_brief",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "view=digest (brief-tools.ts) is rendered for the caller below local reach - renderDigest " +
      "is handed readableAtContextReach(ctx), so a reserved preference or retired record is " +
      "absent from its rows and counts (a dream shared with one is counted with its readable " +
      "transitions only), and no report snapshot is taken or delta shown; " +
      "view=morning is handed the same predicate and leaves such a preference out, and shows " +
      "no pending trigger or trigger-queue failure and marks nothing delivered; view=daily " +
      "and view=weekly answer at the caller's reach for the ids they name - a status " +
      "transition, retirement or contradiction naming a record the caller cannot read (under " +
      "its pref- or ret- spelling) is dropped through readerRefView, source_pointers are " +
      "recollected from the evidence events the caller may see, events_by_kind and vault_delta " +
      "are recomputed from that same event selection (evidence on a withheld record, a dream " +
      "whose every transition is withheld and any other event scoped to a withheld record are " +
      "not counted), and no report snapshot is taken or delta shown; view=today renders its " +
      "recent activity through the shared log-event rule (log-events-at-reach.ts via " +
      "reach-events.ts) before the limit and the totals, so an event naming a withheld record " +
      "is absent and a shared dream shows only its readable transitions, and lists an obligation " +
      "or an open loop only when readableAtContextReach(ctx) passes its page, tested before the " +
      "note is read, so neither its text, its path nor the totals move; view=monthly counts the " +
      "month's events through the same log-event rule before the transition, retirement, " +
      "contradiction and neglected-area counts; view=operator takes its doctor counts over the " +
      "findings the owner view ANDed with reachView keeps (the doctor pass itself handed " +
      "readableAtContextReach(ctx), so the removed-tool and uncertain caps, the " +
      "stale-dependency states and consumers and the semantic-health detectors count only " +
      "readable pages), its digest counts over the preference, retired and inbox pages the " +
      "caller may read, its instruction-file warnings over the vault-root files the caller may " +
      "read, its top actions by target before the top-N slice, its verification entries and " +
      "their counts by the record and page each names, and the trust verdict again over those " +
      "kept streams. " +
      "Residual: the operator view's dream_summary counts (dream warnings, uncertain and " +
      "quarantined entries of the dry-run dream), and the dream warnings the trust verdict " +
      "folds in, are still taken over the whole Brain layer and name no id.",
  },
  {
    surface: "brain_analytics",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "view=timeline, view=belief_evolution and view=concept_synthesis answer at the caller's " +
      "reach (analytics-tools.ts via reach-events.ts): a timeline event naming a record the " +
      "caller cannot read under its pref- or ret- spelling is dropped before the limit and the " +
      "total, a shared dream is kept while one transition is readable; a belief-evolution row " +
      "is asked over every record it names and a refused pref_id target answers as an absent " +
      "one; a concept-synthesis linker or mention from an unreadable page is dropped and a " +
      "refused target answers as an empty cluster. Residual: view=attention_flows and " +
      "view=dedup are filtered by the gated owner view only, never by reach.",
  },
  {
    surface: "brain_pre_compress_pack",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "buildPreCompressPack (core/brain/pre-compress-pack.ts) is handed " +
      "readableAtContextReach(ctx): the top-K walk skips a preference the caller cannot read, " +
      "and below local reach the active head is always the reader render of Brain/active.md.",
  },
  {
    surface: "brain_pre_compact_extract",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "extractPreCompactRecords (core/brain/pre-compact-extract.ts) extracts records from " +
      "caller-SUPPLIED conversation text, not from vault notes - included for completeness of " +
      "the file-level sweep rather than as a real vault-content disclosure.",
  },
  {
    surface: "brain_recall_gate",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "a diagnostic classifier over caller-supplied scores/match_quality - it runs no search and " +
      "returns no note content; included for completeness of the file-level sweep only. Its " +
      "corpus statement below local reach carries no coverage receipt and no index count, for " +
      "every state (corpusVerdictAtReach, withoutCorpusCounts), and its root coverage answers " +
      "at the caller's reach the same way brain_search's does (probeRetrievalCorpus with " +
      "contextReach).",
  },
  {
    surface: "brain_recall_feedback",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "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. " +
      "refresh plans only the derived pages readableAtContextReach(ctx) keeps, so a withheld " +
      "stale or orphaned page is neither named, re-derived nor archived.",
  },
  {
    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_skill_rewrite_status",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "reads one skill's benchmark-gated rewrite lane status: the frozen benchmark receipt, " +
      "the grade ledger's verdict-and-rate rows for that skill, and the slug of a staged " +
      "proposal awaiting a human accept. It names no note path, title or body at any reach - " +
      "the same ids-and-rates discipline as the grade record itself - so there is no page " +
      "content for a read root to withhold, and MCP never accepts or scores regardless.",
  },
  {
    surface: "brain_procedural_memory",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the handler filters list through readableAtContextReach(ctx) and recounts its total, " +
      "reports reconcile counts over readable pages only, and refuses mark_used and " +
      "mark_outcome on a withheld entry with the unknown-id error, before writing, so a " +
      "procedure page the caller may not read at its reach is answered as an absent one.",
  },
  {
    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",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "reports codegraph index state and counts - no vault note crosses this surface at all; " +
      "included for completeness of the file-level sweep only.",
  },
  {
    surface: "brain_context_presets",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "diagnoses/suggests context-pack preset configuration and returns config diffs, not note " +
      "content; included for completeness of the file-level sweep only.",
  },
  {
    surface: "second_brain_capabilities",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "returns the process's own capability report (tool counts, withheld-tool reasons) from " +
      "ctx.capabilityReport - it never touches the vault, let alone a note path, title or body; " +
      "included for completeness of the file-level sweep only. Registered as " +
      "`name: CAPABILITY_DIAGNOSTIC_TOOL` rather than a literal, which is exactly why the sweep " +
      "resolves constants: this row was missing while the census passed.",
  },
  {
    surface: "second_brain_status",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "reports install/config/vault status blocks - no note path, title, or body crosses this " +
      "surface, but its Brain block is computeBrainStatus over the whole Brain layer, so the " +
      "preference counts and the last apply-evidence time move with a reserved record (a " +
      "stated, deferred residual); included " +
      "for the file-level sweep (tools.ts imports listVaultPages for second_brain_query, defined " +
      "in the same file).",
  },
  {
    surface: "vault_health",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "runs vault/config/plugin-manifest health checks and state-surface inventory - no note " +
      "content crosses this surface; included for completeness of the file-level sweep only.",
  },
  {
    surface: "brain_obligation",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "every operation asks readableAtContextReach(ctx) about Brain/obligations/<slug>.md " +
      "before the page is read or written: list keeps only the obligations the caller may read, " +
      "show answers a withheld slug as an absent one ({present: false}), and done and remove " +
      "refuse it with the 'no obligation' error an absent slug gets, so the page is neither " +
      "completed nor archived. Below local reach remove leaves the archive name, which steps " +
      "past withheld archived pages, out of the answer. Residual: add over a taken slug is " +
      "refused whoever may read the page, because creating it would replace the withheld page.",
  },
  {
    surface: "brain_agenda",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "swept in for file-level completeness because calendar-tools.ts also registers " +
      "brain_obligation: synthesizeAgenda folds the caller-supplied calendar events into " +
      "conflicts and focus blocks and never reads a vault page, so no note path, title or body " +
      "crosses this surface.",
  },
  {
    surface: "brain_pledge",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "every operation asks readableAtContextReach about Brain/pledges/<slug>.md before the " +
      "page is read or written, exactly as brain_obligation does: list keeps only the pledges " +
      "the caller may read, show answers a withheld slug as an absent one ({present: false}), " +
      "and fulfill and remove refuse it with the 'no pledge' error an absent slug gets, so the " +
      "page is neither stamped nor archived. Below local reach remove leaves the archive name, " +
      "which steps past withheld archived pages, out of the answer. Residual: add over a taken " +
      "slug is refused whoever may read the page, because creating it would replace the " +
      "withheld page. add asks the same reach check about the cited source page before its " +
      "evidence quotes are verified against the page's raw bytes, refusing a withheld source " +
      "identically to an absent one, exactly as the intake beside it gates its whole batch.",
  },
  {
    surface: "brain_intake_pledges",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the intake asks readableAtContextReach(ctx) about the cited source page before anything " +
      "is validated against its bytes: a source the caller may not read refuses the whole " +
      "batch identically to an absent one, so no quote containment verdict, title or evidence " +
      "text derived from a withheld page crosses, and nothing is written. Created pledge pages " +
      "land in the caller's own lane under Brain/pledges/ and the answer names only slugs the " +
      "intake itself just wrote.",
  },
  {
    surface: "brain_trigger",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "scan runs scanTriggers handed readableAtContextReach(ctx), so its semantic-health and " +
      "retention sources read only the records the caller may read: the candidates total counts " +
      "none it may not, and a scan from a remote caller writes no trigger about a withheld " +
      "record. Every trigger row - created, skipped, list, history - is kept only when each " +
      "artifact it names (source_artifacts, the wikilinks in its reason, the cooldown key " +
      "segments) passes the gated owner view ANDed with reachView, and a transition on a trigger " +
      "the caller may not see is refused with the 'unknown trigger' error an absent id gets.",
  },
  {
    surface: "brain_intention",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "list and show return intention chains - Brain-authored scope records with their text, " +
      "history and path; the handler asks readableAtContextReach(ctx) about each chain's page, " +
      "so below local reach a withheld chain is listed by no row, shown as absent and refused " +
      "by move with the error an absent scope gets. set over a withheld chain is refused rather " +
      "than read and rewritten (the one answer that cannot match an absent chain's), and move " +
      "leaves the archive name, which steps past withheld history files, out of the answer.",
  },
  {
    surface: "brain_stale_scan",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "findStaleEntries walks the preference and signal records and names each stale one by id, " +
      "topic and vault-relative path; the handler keeps a row only when its path and id pass the " +
      "gated owner view ANDed with reachView, so below local reach a withheld record is listed " +
      "by no row. stale_log_files names Brain/log shards by date, which are shared by " +
      "construction and carry no page content.",
  },
  {
    surface: "brain_review_candidates",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the dry-run dream preview runs with previewReadable bound to readableAtContextReach(ctx), " +
      "so below local reach it clusters, counts and routes only the signals, preferences and " +
      "retired records the caller may read: clusters_below_threshold and intent_reviews fold no " +
      "withheld signal. would_create, would_promote, would_retire, would_supersede and " +
      "gated_retires keep a row only when both the pref- and the ret- spelling of its id pass " +
      "the gated owner view ANDed with reachView, and signal_novelty asks the same of each " +
      "signal's path and id. retire_siblings pairs two preference ids, and a pair is kept and " +
      "counted only when both ids pass the same view, so a withheld retiring or sibling " +
      "preference moves neither a row nor a count.",
  },
  {
    surface: "brain_retention",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "buildRetentionReview names retired preferences and processed signals by id and " +
      "vault-relative path; the handler keeps a recommendation only when its path and id pass " +
      "the gated owner view ANDed with reachView, and counts the summary again over the kept " +
      "rows, so a withheld record moves neither a row nor a count.",
  },
  {
    surface: "brain_tension",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "detect hands detectTensionsInVault readableAtContextReach(ctx), so a note the caller " +
      "may not read is skipped before it is opened: it is not counted in scanned_files, takes " +
      "part in no pair and names no tension. A persisted tension page carries the stricter " +
      "visibility of its two source notes (strictestVisibility), and list, verify, show and the " +
      "confirm, dismiss and resolve transitions ask the same predicate about the tension page's " +
      "vault-relative path, answering a withheld one as absent ('no tension') before any write.",
  },
  {
    surface: "brain_lifecycle",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "tombstone, supersede and temporal-replace resolve each page argument through " +
      "resolveNotePath with readableAtContextReach(ctx): a page the caller may not read is " +
      "refused with the 'note does not exist' error a missing page gets, before anything is " +
      "written. curator keeps a slice row only when its key (a page path or a memory id) passes " +
      "the gated owner view ANDed with reachView. tip builds its chain lookup over the Brain " +
      "pages readableAtContextReach(ctx) keeps (buildChainLookup), so a withheld id reads as " +
      "unknown and a walk stops at it.",
  },
  {
    surface: "brain_derive_fact",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "deriveFact is handed readableAtContextReach(ctx): a premise preference the caller may " +
      "not read is refused with the missing-premise error before anything is written. A slug " +
      "colliding with a withheld preference still refuses as existing, the inherent " +
      "create-collision residual.",
  },
  {
    surface: "brain_decision",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "every action asks readableAtContextReach(ctx) about Brain/decisions/decision-<slug>.md: " +
      "list, compare, similar and recall skip a page the caller may not read; show, outcome and " +
      "rate refuse it with 'no decision: <slug>' before any write; history drops receipts whose " +
      "subject the gated owner view ANDed with reachView hides, before the total and paging. " +
      "record over an occupied withheld slug refuses 'decision already exists', the inherent " +
      "create-collision residual; the review obligation record opens names the decision's title " +
      "at default visibility unless the operator reserves it too. Delivery shaping " +
      "(delivery-trust, lane A): the decision page's stored free-text payload fields - show's " +
      "assumption, premortem and outcome, the compare rows' rationale and outcome, the list and " +
      "similar rows' outcome - plus the recall render and the open-decision question, context " +
      "and discard-reason prose are fenced at remote reach through the shared delivery binding, " +
      "byte-identical at local reach. The identifiers (title, chosen, slug), the enumerated " +
      "options, the structured fields, the write echoes of caller-authored values, and the " +
      "change-history receipts (prefixed state grammar, the ledger boundary) stay untouched.",
  },
  {
    surface: "brain_scaffold_stub",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "list drops sources the caller may not read (the owner scope ANDed with " +
      "readableAtContextReach(ctx)) and a target left with no readable source; write refuses an " +
      "unreadable source as unknown_source; the target_resolves and target_ambiguous refusals " +
      "name no unreadable path. An occupied withheld target still refuses, the inherent " +
      "create-collision residual.",
  },
  {
    surface: "brain_note_lifecycle",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "swept in for file-level completeness because lifecycle-file-tools.ts also registers " +
      "brain_scaffold_stub: rename, move, archive and delete resolve the note through the reach " +
      "predicate and refuse a page the caller may not read with the error a missing note gets, " +
      "before anything is read or written. A move or rename onto an occupied withheld " +
      "destination still refuses as occupied, the inherent create-collision residual, and an " +
      "applied move still rewrites links inside withheld pages without naming them.",
  },
  {
    surface: "brain_create_note",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the write receipt carries the page lint (core/brain/page-lint.ts lintWrittenPages, through " +
      "notes-tools.ts noteWriteResult), whose near-duplicate hint names sibling pages by path and " +
      "counts the siblings it skipped or could not read; noteWriteResult binds the lint to " +
      "readableAtContextReach(ctx), so a sibling the caller may not read is dropped at the " +
      "directory listing, before it is scored and before candidates_skipped or " +
      "candidates_unreadable count it; the wikilink and merged-link checks ask the same " +
      "predicate, so a link to a withheld Brain page reads as broken and a merge chain ends at " +
      "its first withheld hop, and the receipt answers as if the page were absent. " +
      "A create onto an occupied withheld path still refuses as occupied, the inherent " +
      "create-collision residual.",
  },
  {
    surface: "brain_update_note",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the write receipt carries the page lint (core/brain/page-lint.ts lintWrittenPages, through " +
      "notes-tools.ts noteWriteResult), whose near-duplicate hint names sibling pages by path and " +
      "counts the siblings it skipped or could not read; noteWriteResult binds the lint to " +
      "readableAtContextReach(ctx), so a sibling the caller may not read is dropped at the " +
      "directory listing, before it is scored and before candidates_skipped or " +
      "candidates_unreadable count it; the wikilink and merged-link checks ask the same " +
      "predicate, so a link to a withheld Brain page reads as broken and a merge chain ends at " +
      "its first withheld hop, and the receipt answers as if the page were absent. " +
      "The target itself resolves through the same predicate and a withheld one is refused " +
      "with the error a missing note gets.",
  },
  {
    surface: "brain_append_note",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the write receipt carries the page lint (core/brain/page-lint.ts lintWrittenPages, through " +
      "notes-tools.ts noteWriteResult), whose near-duplicate hint names sibling pages by path and " +
      "counts the siblings it skipped or could not read; noteWriteResult binds the lint to " +
      "readableAtContextReach(ctx), so a sibling the caller may not read is dropped at the " +
      "directory listing, before it is scored and before candidates_skipped or " +
      "candidates_unreadable count it; the wikilink and merged-link checks ask the same " +
      "predicate, so a link to a withheld Brain page reads as broken and a merge chain ends at " +
      "its first withheld hop, and the receipt answers as if the page were absent. " +
      "The target itself resolves through the same predicate and a withheld one is refused " +
      "with the error a missing note gets.",
  },
  {
    surface: "brain_write_batch",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "the write receipt carries the page lint (core/brain/page-lint.ts lintWrittenPages, through " +
      "notes-tools.ts noteWriteResult), whose near-duplicate hint names sibling pages by path and " +
      "counts the siblings it skipped or could not read; noteWriteResult binds the lint to " +
      "readableAtContextReach(ctx), so a sibling the caller may not read is dropped at the " +
      "directory listing, before it is scored and before candidates_skipped or " +
      "candidates_unreadable count it; the wikilink and merged-link checks ask the same " +
      "predicate, so a link to a withheld Brain page reads as broken and a merge chain ends at " +
      "its first withheld hop, and the receipt answers as if the page were absent. " +
      "Every page the batch committed is linted under the one predicate, and the update and " +
      "append operations refuse a withheld target with the error a missing note gets.",
  },
  {
    surface: "brain_expire",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "setExpiration is handed readableAtContextReach(ctx) and passes over a candidate file the " +
      "caller may not read as if it were not there, so a withheld signal or preference is " +
      "refused with the unknown-id error (ExpirationTargetNotFoundError, the same searched " +
      "list) and nothing is written to it.",
  },
  {
    surface: "brain_feedback",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "it writes the caller's own inbox signal (and, with force_confirmed, its preference) from " +
      "the caller's arguments; the conflict advisory and the routing hint " +
      "(adviseIncomingFeedback, adviseUnroutableCapture) score and count only the preferences " +
      "and signals readableAtContextReach(ctx) keeps. force_confirmed over an occupied withheld " +
      "slug still refuses with 'preference already exists', the inherent create-collision " +
      "residual: only overwriting the page would hide it.",
  },
  {
    surface: "brain_note",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "swept in for file-level completeness because feedback-tools.ts also registers " +
      "brain_expire: appendBrainNote appends the caller's own line to today's log and answers " +
      "with the log path and agent; it reads no vault page.",
  },
  {
    surface: "brain_observed_use",
    kind: K.mcpTool,
    category: C.excluded,
    reason:
      "swept in for file-level completeness because feedback-tools.ts also registers " +
      "brain_expire: emitObservedUse stores the caller-supplied verdicts as one continuity " +
      "record and answers with its id, the entry count and the timestamp; it reads no vault page.",
  },
  {
    surface: "brain_apply_evidence",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "appendApplyEvidence is handed readableAtContextReach(ctx): a preference the caller may " +
      "not read is refused with the missing-preference error (BrainPreferenceNotFoundError) " +
      "before any write, exactly as an absent id, and the apply_evidence operation of " +
      "brain_write_batch asks the same predicate.",
  },
  {
    surface: "brain_dream",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "Below local reach only a dry run is served, planned over the records the caller may read " +
      "as if the others were absent (previewReadable, the readableAtContextReach(ctx) " +
      "predicate); a real pass, a single step and the staged lifecycle are refused with one " +
      "fixed answer before anything is read or written. A preference the pass drafts carries " +
      "the strictest visibility of the signals it is drafted from and of the record it " +
      "supersedes or rebuts (strictestVisibilityOf), so reserved signal text never becomes a " +
      "default-visibility preference; a refresh keeps the page's own visibility line.",
  },
  {
    surface: "brain_intent_review",
    kind: K.mcpTool,
    category: C.covered,
    reason:
      "buildIntentReview folds inbox signal clusters into a topic, a decision, a signal count " +
      "and a risk band; the handler hands it readableAtContextReach(ctx), so below local reach " +
      "it folds only the signals and rejected retired records the caller may read, and a " +
      "withheld one moves no topic, count or decision.",
  },

  // --- Excluded: CLI verbs, one per MCP tool above that has a CLI mirror ----
  {
    surface: "search expand",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "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.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",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/bridges.ts drives the same bridge-discovery.ts core as brain_bridges.",
  },
  {
    surface: "brain clusters",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "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",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/moc-audit.ts calls auditMoc, the same buildBacklinkIndex-backed, " +
      "visibility-blind path brain_moc_audit uses.",
  },
  {
    surface: "brain deep-synthesis",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "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",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/ideas.ts drives the same idea-discovery.ts core as brain_idea_discovery.",
  },
  {
    surface: "brain dead-end",
    kind: K.cliVerb,
    category: C.excluded,
    reason: "src/cli/brain/verbs/dead-end.ts drives the same dead-ends.ts core as brain_dead_ends.",
  },
  {
    surface: "brain file-context",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "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",
    kind: K.cliVerb,
    category: C.excluded,
    reason: "src/cli/brain/verbs/context-pack.ts calls packContext, same as brain_context_pack.",
  },
  {
    surface: "brain query",
    kind: K.cliVerb,
    category: C.covered,
    reason:
      "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",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/sources.ts calls aggregateSources, the same Brain signal-registry " +
      "read brain_sources uses, with no visibility check either.",
  },
  {
    surface: "brain audit",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/audit.ts calls readPrefAudit, the same preference-mutation ledger " +
      "read brain_audit uses; no note body or title crosses either surface.",
  },
  {
    surface: "brain attest",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/attest.ts drives the same attestation kernel as brain_attestations " +
      "in the operator's own shell, plus keygen and sign, which mint keys and signed records " +
      "under .open-second-brain/ and read no vault page at all; no note path, title or body " +
      "crosses any of the four subverbs.",
  },
  {
    surface: "brain claims",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/claims.ts drives the same claim-graph core (path, topic, principle " +
      "text per row) that brain_claims's own docblock describes as agent-scope-gated only.",
  },
  {
    surface: "brain truth",
    kind: K.cliVerb,
    category: C.excluded,
    reason: "src/cli/brain/verbs/truth.ts drives the same entity claim ledger as brain_truth.",
  },
  {
    surface: "brain label",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/label.ts drives the same labels.ts core as brain_labels; neither " +
      "surface returns a note title or body, only the caller's own path and a label set.",
  },
  {
    surface: "brain tiers",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/tiers.ts drives the same Store.listTierDrift() path as brain_tiers.",
  },
  {
    surface: "brain secret",
    kind: K.cliVerb,
    category: C.excluded,
    reason: "src/cli/brain/verbs/secret.ts mirrors brain_secrets; no note content crosses either.",
  },
  {
    surface: "brain maintenance",
    kind: K.cliVerb,
    category: C.excluded,
    reason:
      "src/cli/brain/verbs/maintenance.ts mirrors brain_maintenance; no note content crosses either.",
  },

  // --- MCP resources ---------------------------------------------------------
  {
    surface: "osb://preferences/active",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "readActive (resources.ts) passes the request view (owner view ANDed with reachView) and " +
      "whether the request is below local reach to readActiveForReader, which serves the shared " +
      "file only to a local reader with no owner scope and otherwise renders the digest without " +
      "the preference and retired records the reader cannot see, stamped with the file's " +
      "generated_at. Delivery shaping (delivery-trust, lane A): the delivered markdown is " +
      "fenced at remote reach through the shared delivery shaper, named for the generated " +
      "file's own absence of stamps; local keeps the bytes.",
  },
  {
    surface: "osb://lessons",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "readLessons (resources.ts) serves Brain/lessons.md's bytes only to a local reader with no " +
      "owner scope; any other reader gets renderLessonsForReader, handed the request view " +
      "(owner view ANDed with reachView): a preference or dead-end it cannot read, and every " +
      "apply-evidence event naming a page it cannot read, is absent, scored at the generation " +
      "on disk. Delivery shaping (delivery-trust, lane A): the delivered markdown is fenced at " +
      "remote reach through the same shaper; local keeps the bytes.",
  },
  {
    surface: "osb://digest/latest",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "readDigestLatest (resources.ts) hands renderDigest the request view below local reach: a " +
      "preference or retired record the caller cannot read is absent from every row and count, " +
      "with the log events, backlink sources and action targets naming one, and the agent " +
      "summary counts only the events the caller may read; the token-footprint action " +
      "measures the whole vault. Delivery shaping (delivery-trust, lane A): the delivered " +
      "markdown is fenced at remote reach through the shared delivery shaper, named for the " +
      "compiled-digest render's own absence of stamps (the same probe the active and lessons " +
      "readers make); local keeps the bytes.",
  },
  {
    surface: "osb://status",
    kind: K.mcpResource,
    category: C.excluded,
    reason:
      "computeBrainStatus() output, same unfiltered whole-vault-reader class; no visibility " +
      "check, so its preference and retired counts move with a reserved record (a stated, " +
      "deferred residual).",
  },
  {
    surface: "osb://preference/{id}",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "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. " +
      "Delivery shaping (delivery-trust, lane A): the whole-file delivery is fenced at remote " +
      "reach, named for the resolved page's own derived provenance; local keeps the bytes.",
  },
  {
    surface: "osb://rule-topic/{slug}",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "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. Delivery shaping (delivery-trust, lane A): the " +
      "synthesis is fenced at remote reach, named for the governing rule's derived provenance " +
      "(the absent-rule probe, fail closed); local keeps the bytes.",
  },
  {
    surface: "osb://topic/{id}",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "a topic is a store record family with no owner line: its privacy is its partition. A read " +
      "below local reach folds the shared partition alone, so a private topic answers byte for " +
      "byte as an absent one (topic ids are ULIDs, not guessable, and still never confirmed), and " +
      "a private item of a shared topic is left off the page.",
  },
  {
    surface: "osb://log/{date}",
    kind: K.mcpResource,
    category: C.covered,
    reason:
      "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.covered,
    reason:
      "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. Delivery " +
      "shaping (delivery-trust, lane A): the rendered document is fenced at remote reach, named " +
      "for the target page's own derived provenance; local keeps the bytes.",
  },

  // --- Excluded: the index's own storage --------------------------------------
  {
    surface: "search index chunks/chunk_fts tables",
    kind: K.indexStore,
    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. 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.",
  },
]);

/** {@link VISIBILITY_SURFACE_REGISTRY}, restricted to the excluded rows. */
export function excludedVisibilitySurfaces(): ReadonlyArray<VisibilitySurfaceEntry> {
  return VISIBILITY_SURFACE_REGISTRY.filter((entry) => entry.category === C.excluded);
}

/**
 * The rows that name something a caller can INVOKE - every kind but
 * `index_store`, whose one row is a structural fact about the index's own
 * storage and says so in its own vocabulary comment.
 *
 * The distinction exists because a count is reported to operators. "N of
 * M note-returning surfaces" has to be M surfaces somebody could call;
 * folding the storage fact into that denominator quietly inflates it by
 * one, which is the kind of arithmetic this wave is about.
 */
export function callableVisibilitySurfaces(): ReadonlyArray<VisibilitySurfaceEntry> {
  return VISIBILITY_SURFACE_REGISTRY.filter((entry) => entry.kind !== K.indexStore);
}

/** {@link callableVisibilitySurfaces}, restricted to the excluded rows. */
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/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.",
  },
]);