| name | sourcevault-packageapi-narrowing |
| description | Use when locating a function, option, symbol, or "where is X handled/implemented" inside this system's own packages (SourceVault, ClaudeOrchestrator, ClaudeRuntime, NBAccess, claudecode, github) — i.e. the initial narrowing step of a code-investigation task, before reading files. Prefer SourceVault MCP packageapi mining over a broad full-text rg sweep of $packageDirectory. Covers concept-token query discipline, sourcevault_get view=body, freshness (StaleDocs) handling, filters.packages scoping, and the bounded grep fallback. |
SourceVault packageapi で対象を絞り込む（MCP first, grep bounded fallback）
このシステム自身のパッケージ（SourceVault / ClaudeOrchestrator / ClaudeRuntime / NBAccess /
claudecode / github）の中で「どの関数か」「どこで X を扱っているか」を探す局面の手順。
$packageDirectory 全体への広い rg から始めない。
なぜ
- 広い全文検索（
rg --files → rg -n "SourceVault|MCP|log|ingest|..."）は
bak\ / test codes\ / _info\history\ / GithubRepositories\（ミラー重複）/
無関係パッケージまで拾い、初動の token・往復・判断負荷が膨らむ（実測で 1 万件超のヒット）。
sourcevault_search kinds=["packageapi"] は各パッケージの api*.md を関数粒度で索引し、
signature / summary / package / freshness 付きの候補を返す。sv://packageapi/... は PublicDoc で
body 取得も grant 不要。ただし自然文やキーワード束クエリでは精度が落ちるため、下記の
クエリ規律を守る。
手順
- 可用性確認は 1 回だけ: セッション最初に
sourcevault_catalog で packageapi が
available か確認する（毎回は呼ばない）。
- 1 呼び出し 1 概念トークンで反復:
sourcevault_search kinds=["packageapi"] を、
ingest / rollup / adapter / mcp / runtime / machine / snapshot / privacy /
log のような単一概念トークンで引く。合計 3〜6 トークンまで、各 limit は 5〜10。
- 自然文（"where are the logs handled"）や
A|B|C の交替束を 1 クエリに詰めない。
- 同一クエリの結果はセッション内で使い回す（再問い合わせしない）。
- package を絞れるなら
filters.packages: 例
filters.packages=["SourceVault","ClaudeOrchestrator"]。canonical 名
（SourceVault / ClaudeOrchestrator / ClaudeRuntime / NBAccess / claudecode / github）で渡す。
- 本文確定は
sourcevault_get view=body|contract|guided（packageapi は grant 不要）で
上位候補の URI / Symbol を取得する。sourcevault_get が tool として見えないクライアントでは、
search 結果の snippet / signature で候補を絞り、その file を Read へ移る。
- 鮮度を見る: 結果の
Freshness が StaleDocs（api ドキュメントがソースより古い可能性）の候補は、
採用前に当該実装ファイルを短く確認する。Fresh は原則そのまま一次候補にしてよい。
- 全文検索は fallback、境界を切る: 次のいずれかのときだけ
rg に落ちる —
packageapi が扱わないもの（ソース本文の実装詳細、on-disk のログ/パス、未文書化シンボル）、
候補 0 件、StaleDocs が上位を占める、MCP 応答が所定秒数を超える。
フォールバックは広く撫でず rg -g "SourceVault*.wl" -g "ClaudeOrchestrator*.wl" のように
glob で境界を切る（bak\ / test codes\ / GithubRepositories\ を避ける）。
注意（性能の但し書き）
sourcevault_search は 1 回あたり数十秒〜約 2 分かかる場合がある（環境・kernel 状態・index rebuild 依存）。
本手順の主効果は 件数削減・往復（推論ステップ）削減・context 汚染回避であって「常に wall time が速い」ではない。
だから手順 6 のフォールバック条件（0 件 / StaleDocs 上位 / タイムアウト）を必ず併記して使う。- これは「コードベースの API を絞り込む」手順。「過去の実行ログを引く」用途とは別レイヤ
（後者は取込済みコンテンツ索引
kinds=["search"] や将来の llmlog adapter の話）。
対象外・非適用
- 外部（非本システム）ライブラリや、Wolfram 標準関数の探索には使わない（それは通常の検索・ドキュメントで）。
- packageapi は
api*.md のみを索引する。未文書化シンボルや「どのファイルの何行か」は grep / Read が要る。
関連
- 設計・比較の根拠:
ドキュメント/sourcevault_mining_narrowing_vs_fulltext_proposal_v0_1.md
- MCP 露出仕様:
SourceVault_info/docs/api_packageapi.md
- ランカー実装:
SourceVault_packageapi.wl（SourceVaultPackageApiSearch）
- MCP adapter:
SourceVault_mcp.wl（iSVPackageApiAdapterSearch）
