Detailed behavior of the API, retrieval, caller evidence, index health, cache, optional LSP evidence and benchmarks. The README is the short tour.
- Exact answers. Every hit carries a
file:linespan, a source hash and an index generation. An agent can cite it and you can check it. - Deterministic by design. Incremental refresh produces the same bytes as a full rebuild. Paths, symbols and edges are sorted before they are written. Runs are reproducible.
- Honest about limits. Results state what was omitted and why. Partial indexes say so on every response. Absence of a caller never claims deletion is safe.
- Local and read-only. One cache directory, no writes inside your repository, no per-agent files to keep in sync, no usage reporting. Indexing and every query run offline. The one command that opens a network connection is
osnova update-check, which asks the npm registry for the latest version and runs only when you type it. - Refreshes as you type. Query commands hash the working tree first and apply only what changed, uncommitted edits included.
- Twenty languages. Deep adapters for TypeScript, JavaScript, Python, Go, Rust, Java and C#. A generic tier for C, C++, Objective-C, Ruby, PHP, Kotlin, Swift, Scala, Dart, Elixir, OCaml, Zig and Bash. Grammars ship as WASM, so there is nothing to compile.
import { buildIndex, ask, renderMapCard } from "@getdomovoi/osnova";
const index = await buildIndex("/path/to/repo");
const hits = ask(index, "where do we validate tokens", { limit: 5 });
const card = await renderMapCard(index); // <= 16,384 code unitsExports include lifecycle (buildIndex, loadIndex, refreshWorkspace, indexGeneration, evidenceFingerprint, applyChanges, freshness, indexHealth), retrieval (ask, findText, findTextDetailed, skeleton, callers, callersDetailed, map, renderMapCard, scopedAsk, impact, taskContext, testsFor, symbolsUnderTest), workspace scanning (scanFiles), diagnostics, optional LSP enrichment, index types, and the MCP stdio main (runMcpStdio).
import { buildIndex, ask, callersDetailed, renderMapCard } from "@getdomovoi/osnova";
const index = await buildIndex("/path/to/repo");
const hits = ask(index, "where do we validate tokens", { limit: 5 });
const callers = callersDetailed(index, "src/auth.ts#verify", { direction: "in", depth: 2 });
const card = await renderMapCard(index);The structured APIs return complete results with omission counts. The text budgets below apply to CLI and MCP presentation only.
osnova_footingwithtask: "change"and the question. The agent gets the seed definitions, who calls them, and which tests touch them. When the call namessymbols, arequested:line counts each status,returned,omitted(found but cut by the budget),unknown(no indexed symbol has that qualified name) andout-of-scope(outsidein), then lists names with the last three statuses before returned ones, up to 512 code units and+N more, so a batch with one bad name does not have to be retried whole;taskContextreturns every name's status asrequested.- Edit.
osnova_settlewith no arguments, which compares HEAD with the working tree. The agent gets the indexed dependents of the changed spans to the requested depth (one hop by default, with the frontier beyond it counted) and checks them before it finishes.
ask ranks individual definitions, not one first-matching line per file. Exact identifier and qualified-member matches take priority over lexical matches; separate name, signature, adjacent-documentation, path and body signals determine ordering within those tiers. Body term frequency is saturated so repeated references cannot win merely by volume. Scores are ranking values, not confidence probabilities.
askDetailed retrieves every ranked candidate by default and reports totalCandidates, omittedHits, truncated, filesSearched, and scope. Supplying a limit records the omitted candidate count. Legacy ask and MCP keep the eight-hit default and existing presentation after a bounded-MCP experiment missed its retention gate; the experiment record preserves that decision.
Camel-case, acronym and snake-case words are searchable, while exact matching preserves whole identifier boundaries, including short names. Multiple relevant definitions from one file may appear; duplicate logical symbol IDs do not. Module-level text and prose files remain searchable as fallback documents. Body text is assigned to its innermost indexed definition rather than repeated into every enclosing class.
osnova_ground over MCP answers in a no-source shape by default (lean: false or full: true inlines source; an explicit lean: true still overrides full), and the CLI does so with osnova ground --lean: one header per hit with file:line, the symbol kind, the qualified name and the definition's own line span, then the indexed signature on the next line, collapsed to one line and clipped at 200 code units. It drops only the inlined source body and the excerpt notice that described it; the definition span that notice carried stays in the header, and hit order, ranking, limits, the also: fold and every omission count are unchanged. A hit with no definition keeps its single matching line. Measured warm over MCP at limit five: on a 160-file Python package the payload fell from 2,333 to 699 bytes (635 to 191 tokens, 70 percent); on a 702-file TypeScript monorepo whose matching definitions are one to three lines each, from 1,096 to 986 bytes (304 to 276 tokens, 9 percent). The saving is the source body, so it tracks the size of the matched definitions. It became the MCP default after a paired agent pilot (15 SWE-bench tasks, three runs each, graded twice independently): matched ground answers were 76 percent smaller, file reads were similar (727 against 735), and no ground call asked for lean: false or full: true; solves were 37 against 36 of 45, and on the 12 tasks both arms solved, counting their repeats together, the lean arm was faster on 10, while cost and new tokens did not differ measurably. Pass lean: false when the next step needs the body and no read will follow.
Excerpts retain exact source line numbers and may include an associated leading comment when it supplies the relevant evidence. Documentation recognition is bounded to adjacent comment-like lines and leading Python docstrings, including common multiline signatures; it is not a complete documentation parser. Query documents are cached per index instance and rebuilt for a new incremental index. filesSearched counts eligible indexed files, not only files with hits. API result limits must be nonnegative safe integers.
An experimental graph adjustment was measured and rejected after improving authored tie cases but reducing a pinned real-repository development ranking score. ask remains fielded lexical definition retrieval. The experiment record preserves the positive and negative evidence; no graph-ranking option is shipped.
scopedAsk detects package scopes from indexed manifests (package.json, Cargo.toml, pyproject.toml/setup.cfg/setup.py, go.mod, pom.xml, *.csproj) and from root package.json workspaces globs and root pnpm-workspace.yaml packages: entries, expanding dir/* and exact dir/name forms against directories that contain at least one indexed file. Every scope is scored once against the same repository-wide IDF as ask. Scopes are merged round-robin in path order, taking one hit from each scope with remaining candidates per round until the limit is reached. alsoMatched is reserved for a future ranked merge and is currently always empty. Package boundaries remain indexed-manifest and workspace-glob boundaries, not verified ownership.
findTextDetailed(index, pattern) returns every non-overlapping, line-based match in the indexed text by default. Its result includes groups, totalGroups, totalMatches, omittedGroups, omittedMatches, truncated, and scope: "indexed-text". Completeness refers to indexed text, not ignored, unreadable or otherwise unindexed workspace content, and not fresh disk state unless the caller refreshed the index.
Optional limit and matchesPerGroup bound the detailed result; both must be nonnegative safe integers. Counts include matches excluded by either limit. Zero limits can hide existing matches and are reported as truncation, not absence.
The existing findText API retains its array result, default 50-group limit, and 10-match-per-group cap. CLI thread and MCP osnova_thread keep those default caps but now display totals and omission notices. Their limit controls groups, not matches per group. Use the detailed API without limits when every indexed occurrence is required. These count limits are separate from the presentation budget below.
Every successful MCP tool response opens with osnova generation <id>, and MCP errors open with osnova error: instead. On the CLI only osnova ground --scoped prints that prefix; osnova settle prints base and current generations, the JSON subcommands carry it in a field (receipt.generation for footing, generation for coverage --json), other subcommands print the answer without one, and CLI errors go to stderr with an osnova: prefix and exit 2. When the index is partial, one osnova foundation: line counts the diagnostics by phase and code (the map card carries its own health line). Outputs stay under fixed budgets (16,384 code units for search, 4,096 for task context, outlines, change impact and claim checks, 2,048 for call graphs and maps). Structured selections print exact omission counts; when text still exceeds the budget, a clipping notice states the omitted code units, so the agent knows when to ask for more.
CLI output messages and MCP text payloads are capped at 16,384 UTF-16 code units (maximumTextResponseCodeUnits), excluding transport framing and the CLI's terminating newline. Diagnostics and errors use the same cap. Larger payloads include an explicit output-clipping notice with the omitted code-unit count; any query counts above that notice describe the structured selection before presentation clipping. Clipping never splits a surrogate pair. These are code-unit limits, not token estimates or limits on computation/memory use.
Structured query APIs are not subject to this text-presentation cap. Search callers needing every indexed occurrence should use findTextDetailed without limits. Ask output identifies excerpt ranges when a definition is not fully displayed, including its existing 400-line full-span limit. Map cards retain their elastic detail dropping and configurable nonnegative code-unit cap; zero returns an empty card.
The function names in this paragraph (integrationFileChecks, hookSettingsObject, formatStopReason, promptCodeNames, grepName, formatGrepNudge) identify the implementation in src/cli/hook.ts and src/diagnostics/doctor.ts; they are not package exports, which are the names listed under API above. osnova setup --apply plans each change (MCP entry, --hooks groups, --instructions block) with the same merge as --preview, refuses on any conflict before writing, backs up each existing file as <file>.bak-osnova-<stamp>, and reports unchanged for work already done. osnova doctor adds client:hook and client:mcp checks that run --version on the osnova commands configured in ~/.claude/settings.json and ~/.claude.json (override the home with DoctorOptions.home) and warn on a version other than its own; integrationFileChecks(home) adds plugin:<opencode|kilo|pi> and skill:claude-code checks for each installed plugin or skill file, ok when it matches the shipped file byte for byte after line-ending normalization, a warning naming the osnova setup --apply command that refreshes it otherwise, and integrations ok when none is installed. A Codex apply ends its notice with the trust step: Codex records trust per hook hash and skips a new or changed hook until the user trusts it in /hooks, which osnova cannot do on the user's behalf. osnova hook --client <claude-code|codex|cursor> shapes the output for the harness: plain text for Claude Code, {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit"|"SessionStart","additionalContext"}} for Codex, {"followup_message"} on stop for Cursor. osnova setup --plugin copies integrations/opencode/osnova.js (OpenCode and Kilo: chat.message, which runs hook session once for its cache warmup and discards the text, then hook prompt) or integrations/pi/osnova.ts (Pi: before_agent_start) into the client's plugin directory; a differing file there is a conflict. osnova setup --skill (Claude Code only) copies integrations/claude-code/skills/osnova/SKILL.md to ~/.claude/skills/osnova/SKILL.md under the same conflict rule. The MCP server's instructions field carries the tool contract on initialize, followed by one line naming the checkout it indexes (This server indexes <root>; ...), so an agent in another worktree sees the mismatch before its first lookup. osnova hook <prompt|session|stop|tool|install-preview> serves editor hooks: the payload (prompt, cwd) arrives on stdin, the workspace is --workspace, then cwd, then CLAUDE_PROJECT_DIR, then the process directory; prompt runs footing (understand, limit eight, depth one) and prints one line per definition of a callable or holder kind and one per relationship inside 1,024 code units; session prints one line, the index size and a pointer to the osnova_* tools (the MCP server's instructions carry the contract; --full-contract restates it for a harness without MCP, as the Pi extension does), or starts a background osnova build, polls for its cache every 200 ms for sessionWaitMs (default 3,000) and then either prints the index size or says the build is running; stop runs git diff HEAD, feeds it to settle at depth one and, when stop_hook_active is false and at least one dependent outside the change exists, prints the dependents grouped by file (formatStopReason(result, maxCodeUnits): files sorted by dependent count, six symbols per file as name:line with the rest counted, whole lines only inside 1,536 code units, then one line counting the omitted files and dependents); the turn continues at most once per diff digest per session (hook-state/<session id>.json under the cache directory, keyed by session_id or Cursor's conversation_id) and, for Claude Code and Codex, only when the dependent count exceeds OSNOVA_HOOK_SETTLE_BLOCK_AT (default 1): Claude Code gets {"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":...}}, Codex {"decision":"block","reason":...}, Cursor {"followup_message":...}; when the turn does not continue, Claude Code and Codex get {"systemMessage":...} and Cursor nothing; all print nothing and exit 0 when the prompt is a slash command or shorter than twelve characters, when no cache exists, or when indexing fails (the reason goes to stderr). prompt seeds from promptCodeNames(prompt): backticked tokens and identifiers with an inner capital, underscore or digit, matched exactly against symbol names of callable and holder kinds, at most four definitions per name and eight in all, and prints nothing when no name matches. tool reads tool_name, tool_input and session_id; grepName takes the pattern of a Grep call or the first pattern argument of a Bash grep, rg or git grep, strips \b, ^ and $, and keeps it only when it is one identifier of three or more characters; formatGrepNudge counts resolved calls edges into every definition of that name and prints {"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":...}} once per name per session (the same hook-state/<session id>.json under the cache directory), nothing when there is no definition or no resolved caller. hookSettingsObject(command, client, nudge, gate) adds the PostToolUse group with matcher Grep|Bash only for Claude Code and only when nudge is true (osnova setup --hooks --nudge, osnova hook install-preview --nudge), and the search gate only when gate is true: a PreToolUse group with matcher Grep|Glob|Bash|mcp__.*osnova.* for Claude Code, and for Codex the same group with shell|grep|glob|search|Bash|Grep|Glob|mcp__.*osnova.* and --adaptive on its command, and beforeShellExecution, preToolUse and afterMCPExecution entries for Cursor. The workspace is --workspace, else the git top level of cwd. MCP applies smaller task-focused budgets to broad structural views: skeleton, task context, change impact and claim checks are 4,096 code units, callers is 2,048, and map is 2,048 including the generation/health prefix. Skeleton selects signatures by indexed incoming/outgoing degree and then presents them in source order; it reports exactly how many signatures were omitted. Callers omits the source file:line suffix when it would repeat the relationship's own location, prioritizes confirmed relationships, retains safety/uncertainty language, and separately counts omitted confirmed and unresolved evidence. When the grouped caller text does not fit, it switches to a summary-first layout: one summary: line with sites and files per directory (directories whose files are all tests last), a via (all): line when every re-exporting group carries the same hop, then groups in a deterministic priority (depth, non-test files before test files, then file, then name) with each site list capped at the largest count that lets every group fit (,+N more); when one line number per group still does not fit, the remaining groups fold into one <file>: +N symbols, M edges line per file and whatever is left is counted in the footer. A capped: line states the cap, the hidden sites and the folded edges. The footer still counts edges exactly. full: true on osnova_warp (--full on the CLI, whose default warp output uses the same 2,048-code-unit layout) prints every site without a cap or summary, under the 16,384-code-unit clipping notice. Each unresolved edge carries nameMatches (candidates, at most five qualified names sorted, and total): the indexed functions, methods and classes in the same language family that share the call's name. plumb attaches the same to name-only claims. These are candidates to read, not resolutions.
These limits affect MCP presentation only. skeleton, callersDetailed and map return structured results; MapResult.droppedHotspots and each DirCluster.droppedHubs disclose intrinsic top-list selection. Increase/narrow queries through APIs rather than treating a compact MCP view as complete.
map, osnova groundwork and osnova_groundwork default to eight directory clusters and report omitted directories, per-directory hubs and global hotspots. maxDirs (--max-dirs on the CLI) must be a safe integer of at least 1; map() rejects anything else with a RangeError, so no surface can clamp or truncate the map silently.
callersDetailed returns status: "ambiguous" with candidate symbols when a bare name matches multiple definitions. Select a qualified name (file#Class.method) to continue. A status: "found" result contains the target, indexed hits, direction/depth, and separate unresolved entries carrying raw edges and traversal depth. Unresolved inbound evidence is name-based, not a confirmed caller; unresolved evidence is never traversed as a dependency.
Each detailed hit includes its original edge, preserving the source call-site path/line separately from the callee definition location. A calls edge sits at the line of the callee name as written: the called identifier, the member, attribute, field or selector name, or the type named by new (a Python decorator factory, a Rust macro and the generic tier alike), so in a chain written one call per line (builder, then .alpha(), then .beta()) the beta call sits on the .beta() line, not on the line where builder starts. Two calls whose names share a line and carry the same name, target, binding and argument count are one edge, as they are when the whole expression sits on one line. references, extends and implements edges also sit at the name; imports edges sit at the import and routes edges at the registration. Extracted edges record syntax provenance and their resolution basis: import-path, same-file-name, imported-file-name, or unique-name. Name resolution remains heuristic even when its status is resolved. Multiple candidates at the preferred tier stay ambiguous with candidate names instead of selecting one arbitrarily; unrelated language families are excluded. TypeScript, TSX and JavaScript share a family. Externally supplied edges without provenance are explicitly unknown when serialized.
A references edge records a function, method or class used as a value rather than called: an identifier in a call or constructor argument, an array or object element (including a shorthand property), the right-hand side of a declaration or assignment, a default parameter, a return value, an arrow body, a ?? or || operand, a ternary branch, a class-field initializer or a template substitution in TypeScript, JavaScript and TSX; a call or keyword argument, a list, tuple, set or expression-list element, a dictionary value, an assignment right-hand side, a default parameter, a return value, an or operand, a conditional-expression branch or an f-string interpolation in Python. The callee position of a call stays a calls edge; property-access receivers and members, type positions, declaration names, typeof, instanceof, string contents, this.member values, JSX tag names and JSX attribute values produce no edge. The identifier must bind through the same lexical or import binding a call would use; a parameter, a local variable, an unbound name or a name whose binding reaches a constant, a type or an import the index cannot follow leaves no edge, and the edge is kept only when it resolves (lexical-definition, import-binding, re-export-binding) or is ambiguous. Decorators and Python from x import y items keep their existing unbound references edges. Warp, reach, tests, unreferenced and settle count a references edge wherever they count a resolved edge and print it as references, distinct from calls; plumb and coverage call-site shares still count call edges only, and coverage reports references and referencesResolved beside them.
An extends edge records declared heritage: the superclass or interface name written in the source. An implements edge records a written implements clause, and is never reported as extends. TypeScript, TSX and JavaScript record the extends clause of a class declaration and the extends clause of an interface declaration as extends, and the implements clause of a class declaration as implements; Python records every entry of a class base list as extends. Class expressions assigned to a variable, and the generic tier languages, record no heritage edge. Both edges run from the declaring class or interface to the base and sit at the line of the base name; the rest of this paragraph applies to both kinds. The name must bind through the same lexical or import binding a call would use, and candidates are filtered to class, interface, struct and trait symbols: a same-named function, constant or type alias is never the base. An unbound or ambiguous name keeps its edge with the basis recorded (bound-symbol-missing, binding-blocked, unbound-global, ambiguous), exactly as a call does; there is no name-heuristic fallback. Warp, reach, tests, unreferenced and settle count an extends or implements edge wherever they count a resolved edge and print it by its kind, distinct from calls and references; plumb and coverage call-site shares still count call edges only, and coverage reports extends, extendsResolved, implements and implementsResolved beside them.
A routes edge records a framework route registration: the HTTP verb and the path written at the site, tied to the handler. Four written facts are required, or no edge is recorded: the receiver of the registration call (or the object a decorator is called on) binds through the ordinary import or receiver bindings to an import from a listed framework package, never by name alone (.get( on a Map records nothing); the member is in that framework's verb set; the first positional argument is a plain string literal, else the edge carries no path; and the handler is a bound name, a member the receiver hints identify, or the decorated definition. Frameworks read: Express (express: get, post, put, delete, patch, options, head, all, and use with a literal mount path, on express(), express.Router() and Router() values), NestJS (@nestjs/common: @Get through @All on a method, @Controller on a class), Flask (flask: route and the verb decorators on Flask and Blueprint values, add_url_rule with view_func, register_blueprint with url_prefix) and FastAPI (fastapi: the verb decorators plus api_route and websocket on FastAPI and APIRouter values, include_router with prefix). route, all, api_route, @All, @Controller and every mount record method ANY; websocket records WEBSOCKET. The edge runs from the enclosing scope of the registration to the handler and sits at the registration line; OsnovaEdge.route carries { method, path? }. What stays unresolved says why: an arrow function, function expression or lambda handler is route-handler-inline, a call result such as wrap(handler) is route-handler-wrapped, a mount whose target is a value the index holds no symbol for (a lower-case Python module variable) is bound-symbol-missing, and an unbound or shadowed name keeps the reason a call would. Prefixes are never composed: @Controller("cats") and its @Get(":id") are two edges, not GET /cats/:id. A registration with one argument (app.get("view engine"), app.use(middleware)) records nothing, and so does use whose first argument is not a literal (app.use(cors(), auth) is middleware, not a mount). Flask's add_url_rule takes the view from view_func= or the third positional argument. A literal path longer than 2,048 code units is recorded as no path rather than truncated. Warp prints the edge as d1 routes <handler>:<line> [<basis>] with a route: <METHOD> <path> detail line, footing, reach, tests, unreferenced and settle count it as a use, and coverage reports routes and routesResolved. osnova_ground indexes every registration as its own document whose name field is the verb and path, so GET /users ranks the registration line first and reports the handler as the hit's symbol when the handler is in the same file; a route whose handler is inline or in another file is a hit at the registration line with no symbol. The sites come from FileCard.routes in the core section ({ method, path?, line, handler? }, where handler is the local qualified name when the handler is declared in the same file), so a route query does not load the edge section. When a method route and the @Controller prefix of its class sit in one file, ground also indexes the composed label (cats and :id answer POST /cats/:id); this composition exists at query time only, the artifact keeps the two edges apart, and no cross-file prefix (include_router, register_blueprint, app.use) is composed. Measured on three pinned checkouts under benchmarks/corpora/ by scripts/routes-corpora.mjs and recorded in benchmarks/results/route-edges-2026-09-21.json: on the FastAPI template, whose runtime route table scripts/route-oracle-fastapi.py dumps, all 23 verb edges are true and all 23 runtime routes are covered; on the Flask checkout 137 edges (113 resolved) and on the NestJS checkout 431 edges (424 resolved), with a 25-edge hand-verified sample of each at 25 of 25.
TypeScript/JavaScript and Python direct calls additionally carry lexical binding hints. Named imports resolve through their source module and exported name, preserving the local call-site name. Named default exports, local export aliases, direct namespace members and known local definitions are supported, with import-binding or lexical-definition evidence. Parameter, destructuring, loop, catch and assignment bindings prevent an imported name from leaking through a shadow; Python function-local assignments apply even before their textual declaration. Missing imported targets do not fall back to unrelated global names. Module-level arrow bodies are attributed to their indexed definition.
Named nested TypeScript/JavaScript definitions and constants are retained under their enclosing qualified names, including declarations inside arrow bodies. Calls from nested arrows use the nested definition's identity rather than being folded into the enclosing function.
Static named re-export chains, JavaScript/TypeScript export * barrels, export * as name namespace re-exports (member access through the namespace resolves to the declaring symbol) and Python named package exports are followed to their declaring symbols. Explicit exports take precedence over stars, stars do not forward default, and competing declarations remain ambiguous. Unknown competing wildcard paths, blocked exports and traversal-budget exhaustion are reported as re-export-incomplete; cycles without a resolved exit are reported as re-export-cycle. Successful chains carry re-export-binding evidence with a deterministic representative via path of export sites. These hops describe module export names, not additional definition IDs.
Import specifiers resolve to indexed files: relative paths with the usual extension and index probing, TypeScript and JavaScript non-relative specifiers through the compilerOptions.paths and baseUrl of the nearest tsconfig.json or jsconfig.json above the importing file (an exact paths key wins, then the * pattern with the longest literal prefix; two patterns with the same prefix length leave the import unresolved with reason import-target-ambiguous; an entry's targets are tried in declaration order with the same extension and index probing, then baseUrl alone, then workspace packages; relative extends chains are followed when the target is named tsconfig*.json or jsconfig*.json, later entries and the extending config overriding earlier ones, and an extends that names a package stops the chain with what the nearer configs declared, since no node_modules is read; comments and trailing commas are allowed; a config is an indexed text file, so editing one re-resolves every edge on refresh; bundler-only aliases such as Vite or webpack resolve.alias are not read), bare specifiers that name a workspace package through its package.json name and exports (every condition is tried, source files first, * patterns expanded) or its module, main and types fields with src/index and src/<subpath> fallbacks, and Python absolute imports through every manifest directory (pyproject.toml, setup.py, setup.cfg) and its src layout. Two packages sharing a name, node: builtins and packages outside the repository stay unresolved. A package.json is scanned even when a .gitignore or .osnovaignore rule matches it, because the manifest maps the package name; configured output and dependency directories are still skipped. Export patterns follow Node's most-specific-prefix rule and a null target excludes the subpath. Python roots are the manifest directories above the importing file, nearest first; a module present under two of them stays unresolved. Export lookup is bounded to 4,096 (module, export-name) states and 128 forwarding hops per requested export, with per-index-resolution memoization. Links persist in FileCard.reExports, so changing a barrel re-resolves unchanged clients. Python relative module paths are normalized within the indexed root, and a package initializer takes precedence over a same-name module file.
An unresolved import that names a package outside the workspace carries an additive external field on its import-target-unresolved resolution: the package name (npm scope and name or first path segment, with node: builtins kept whole; the first dotted segment of a Python absolute import; the Go module path from a go.mod require entry, or the whole import path for the standard library; the Rust crate head when std, a Cargo.toml dependency table or Cargo.lock knows it) and, when the nearest lockfile above the importing file pins exactly one version for it, @<version>. Lockfiles read are pnpm-lock.yaml (per-importer versions, then unique package versions), package-lock.json, yarn.lock, uv.lock, poetry.lock, Pipfile.lock, pinned requirements*.txt, go.mod, go.sum and Cargo.lock; no package registry, node_modules or site-packages is read. Relative imports, path aliases, workspace packages, workspace Go modules, workspace crates and Rust module heads no manifest declares stay unlabelled, so a bare import-target-unresolved means an in-repo import the index could not follow. Text output prints reason: import-target-unresolved (external:<package>@<version>), resolutionCoverage adds externalImportCalls and byExternal counts, and the coverage text splits the reason into (external N, in-repo M) with the ten most-called packages. Lockfiles are indexed files, so their content hash is already part of the index generation, and a changed lockfile re-resolves every edge on refresh.
For TypeScript/JavaScript and Python, member calls use a syntax-backed receiver hint rather than a global method-name match. Supported evidence is an explicit class reference, a direct constructor site or local constructor assignment, lexical JavaScript this in indexed methods (including nested arrow capture), an unshadowed Python method receiver, or a Python parameter whose annotation is a plain or dotted class name that resolves to an indexed class (basis annotation; a None union or Optional[...] names the non-null type, other unions, string annotations and reassigned parameters stay unbound). The declared class and member kind must agree. When the declared class lacks the member, declared extends clauses (TypeScript classes and interfaces) and Python base classes are followed for up to eight hops; the lookup stays unresolved when any base cannot be identified, when two base chains supply different members, when the chain cycles, or when a declaration carries a non-method field of that name. implements clauses are never followed. Class and interface symbols carry heritage (the declared bases as local or import bindings) and fields (own non-method member names) so the walk can be audited. TypeScript annotations on parameters, fields, constructor parameter properties and locals, Python class-body annotations and @property return annotations, fields assigned exactly once in the constructor from a constructor call, and the declared return type of the callee that produced a value (make().m(), const x = make(); x.m(), chains through : this and -> Self, bounded at six calls) also act as receivers, as does the value inside a wrapper once it is taken out (unwrapped on the callee: await f() on a Promise<T> or PromiseLike<T> annotation, await on a Python async function's declared result, and Rust f()?, f().unwrap() or f().expect(..) on a Result<T, E> or Option<T> return type; the wrapper itself stays the receiver without the unwrap), and the contents of a collection: class and interface symbols carry elementTypes and valueTypes per field, functions carry elements and values for a returned collection, and an element receiver owner (with mode value for map.get(k) and map.forEach((v) => ..), or either for values(), subscripts and forEach on an unknown container) resolves through those tables, through the single-base heritage walk for fields, and through builtin pass-through calls (filter, slice, concat, reverse, sort, values); loop variables (for..of, Python for and comprehensions), array callback parameters and local aliases of member chains or indexed elements are bound this way when the name is not reassigned in the enclosing body (TypeScript and Python); in Go, Rust, Java and C# the typed collector records the same tables from slice, array, map, Vec, HashMap, List, Map, Dictionary and IEnumerable types, binds the second range variable, Rust for over a reference or iter(), Java enhanced for, C# foreach, the untyped first parameter of a lambda passed to a known collection method, and index access, and carries in-file contents through pass-through calls such as iter(), stream() and Where(..); in those four languages a reassignment never unbinds a name, since its static type is fixed for its lifetime, a closure sees the enclosing method's receiver (self, or the Go receiver name unless a closer binding shadows it), a Rust if let Some(x) = e, while let and a Some(x) => or Ok(x) => match arm bind x to what e wraps (the inner type of an Option or Result annotation, or the unwrapped return of a call), a Rust use inside an inline mod binds in that module only, a brace-rooted use { a::B, c::D } binds each item, a path whose head is another crate of the Cargo workspace (its [package] name, hyphens as underscores) resolves against that crate's src, and a crate root's pub use is a named or star re-export the resolver follows; a type parameter with a trait or interface bound (Rust T: Runner or a where clause, Java T extends Runner, Go [T Runner], C# where T : IRunner) names that bound, the first bound that is not a marker such as Clone, Cloneable or class, so a call on the parameter resolves to the trait or interface method, and a Rust self.field whose struct type is a struct parameter takes the impl block's argument in that position and its bounds; and TypeScript namespace members are reached through the namespace name (namespaces are module symbols; a namespace merged with a class or interface shares its qualified name), a namespace import forwarded by name (import * as ns; export { ns }) is a namespace re-export, and a call on a namespace member's result follows that export's return type; a type position names the interface or type alias even when a const shares the name; a callee's overload declarations, whether same-file or reached through an export map, must agree on the return type (TypeScript indexes the implementation signature only), and a callee without an annotation whose every own return statement is a new expression of one class, a Python call of one name, or this records that as its return (nested functions and classes are not searched; any disagreement, bare return or generator leaves it unknown), coroutines and generators do not count, and intermediate callees pass the same member-kind checks as direct calls. Class, interface and struct symbols carry fieldTypes (each typed field's declared type as a local or import binding, relative to the holder's file); a member access on an identified receiver (this.pool.conn.send(), param.field.m(), make().field.m()) becomes a field owner that resolution follows through the holder's fieldTypes, then its single-base heritage walk, bounded at six hops. Two declarations of the holder that disagree on the field type, a field the holder lists without a type, or a field written more than once in its own constructor leave the chain unresolved. Conflicting member identities, properties returning callables and unknown receivers stay unresolved. receiver-hint evidence records the class symbol, class/instance mode and basis, retaining export hops when the class came through a barrel.
Python's bare, unshadowed staticmethod, classmethod and property decorators are recognized conservatively. JavaScript static/instance access is distinguished. Reassigned local instances, shadowed receiver parameters, before-initialization reads of local constructed variables and explicit local property writes block affected hints. This is not full alias, mutation, annotation or control-flow inference: cross-object/cross-file changes, custom decorators and constructor return overrides can still change runtime behavior. Receiver hints are not runtime type proofs. Go, Rust, Java and C# use a typed-binding collector (src/extract/typed-bindings.ts): typed parameters, typed locals, constructor literals, declared return types, class and struct fields, this, self and the Go receiver bind a receiver to a type name, and a field of a bound receiver (s.pool.Conn.Hit(), self.rdr.fill()) resolves through the holder's recorded fieldTypes; the type resolves in the file, through an import binding (Go packages via go.mod, Rust paths via the crate root, Java imports via the package path) or, when exactly one declaration of that name exists in the language family, by unique name. Methods carry static/instance member kinds. A generic instantiation or an array binds its base type (Map<K, V> is a Map), and a type name no indexed file declares classifies the call as unbound-global. Go result lists become returnTuple, one binding per position, and a multi-name short declaration from one call takes each name from its position. A member call whose receiver cannot be bound stays unresolved rather than matching by name. super.m() (TypeScript, Java), base.m() (C#) and super().m() (Python) resolve to the single declared base of the enclosing class; more than one base stays unresolved. The remaining generic-tier adapters retain their documented name heuristics. When a field, element or return chain cannot be followed, resolution reports why: unbound-global when the recorded type at the end of the chain is one no indexed file declares in that language family (a builtin or a dependency type), import-target-unresolved when it sits behind an import the index cannot follow, and receiver-unresolved otherwise, including chains that end on a type parameter of an enclosing declaration.
This is declaration-aware analysis of static export syntax, not execution or compiler validation. Rebinding conflicts, type-only runtime calls, Python wildcard imports, global/nonlocal and match scopes are conservative; CommonJS export assignments, exported namespace objects, anonymous defaults and arbitrary receiver/value flow remain unsupported. Missing local definitions and blocked bindings remain explicit unresolved evidence.
CLI warp and MCP osnova_warp use this detailed behavior with their existing arguments. The legacy callers API retains its deterministic selection and result shape. Every found result also carries reach, exact counts from the index and never a score: d1 is the incoming edges into the symbol with the distinct caller files and directories they come from, d2 the incoming edges into those depth-1 callers (a caller reached through two paths is expanded once, and its file counted once), unresolvedSameName the unresolved call edges whose name matches the symbol, the same edges warp lists as unresolved evidence, and tests the test files testsFor lists for it, by resolved edge or file import. The depth-2 walk stops after 2,000 edges and the text then says d2 >2000. The text form is one line under the warp symbol line, reach: d1 callers 66 in 11 files (3 dirs); d2 +14 in 2 files; unresolved same-name 8; tests 13, with the depth-2 segment omitted when the symbol has no callers. taskContext attaches the same counts at depth 1 only to each seed definition (ContextDefinition.reach), printed as an indented reach: line under the definition header, and map reports inFiles, the depth-1 caller file count, on every hub and hotspot entry, printed on hotspot lines as in N from F files. Detailed queries require a positive safe-integer depth. Neither a graph hit nor an empty result proves runtime behavior: current resolution is heuristic, not type inference, and missing callers do not establish that deletion is safe.
resolutionCoverage(index) returns per-language and total rows of files, symbols, call edges, resolved, ambiguous and unresolved counts, resolved counts by method, unresolved counts by reason, the share of resolved call sites, the count of call sites that go through an import the index cannot resolve (unresolvedImportCalls, the import-target-unresolved reason), the count that call a name with no binding in the file (unboundGlobalCalls, the unbound-global reason: builtins and ambient globals), the share of resolved call sites among those not blocked by an unresolved import (resolvedShareExcludingUnresolvedImports) and the share among those blocked by neither (resolvedShareExcludingExternal). Limitations are exactly indexed-call-sites-only, resolution-is-heuristic-not-type-inference, unindexed-files-not-counted, unresolved-import-calls-are-import-target-unresolved-edges, unbound-global-calls-are-names-with-no-binding-in-the-file. scripts/coverage-corpora.mjs runs it on pinned checkouts and refuses a checkout whose revision differs from its manifest or that has modified tracked files. The resolution coverage record holds the measured shares the README quotes.
A call site counts as resolved when the index ties it to one definition through evidence it can name: an import binding (relative paths, and bare specifiers that name a workspace package through its package.json name and exports, or a Python package under a manifest directory or its src layout), a lexical definition in the same file (one the file declares in exactly one scope: when a file declares the same name in two scopes, such as a const inside two test callbacks, the index keeps one record per qualified name, so no edge can name the declaration a given site sees and every call to that name stays unresolved with reason shadowed-declaration; declarations that share one scope, such as overload signatures with their implementation, a value and a type of the same name, or the branches of a conditional definition, are one declaration and still resolve), a re-export chain it followed, or a receiver it could identify (this, a constructor site, a class reference, an annotated parameter, field or local, a field assigned once in the constructor, the declared return type of the function or method that produced the value (or, without an annotation, the constructor it returns on every path), a field of any of those whose declared type the holder records, so this.pool.conn.send() follows two field types across files, or the value inside a wrapper: await f() on a Promise<Foo> return type, and Rust f()?, f().unwrap() and f().expect(..) on Result<Foo, E> and Option<Foo>; and the element or value of a collection whose annotation names it: for (const x of xs), xs.forEach((x) => ..), xs[0], map.get(k), map.values() over Foo[], Set<Foo>, Map<K, Foo>, list[Foo] and dict[K, Foo], including fields and return types in other files, and a local that aliases a member chain), and a TypeScript namespace member reached through the namespace name, including members inherited through declared extends clauses and Python base classes when every base in the chain is identified and agrees. implements clauses are not followed. Everything else stays unresolved with a reason, and every answer from Osnova says so. Go, Rust, Java and C# receivers come from typed parameters, typed locals, constructor literals, declared return types, struct fields, this, self and the method receiver; Go package imports resolve through go.mod, Rust paths through the crate root, Java imports through the package path, and a type declared exactly once in the language family is found without an import. The shares the README quotes are measured on the pinned checkouts (three retrieval corpora plus four coverage-only corpora under benchmarks/corpora/) by scripts/coverage-corpora.mjs (which also reloads each index from its cache and checks the edge count and resolved count match) and recorded in benchmarks/results/resolution-coverage-2026-09-21b.json.
A call through an import the index cannot resolve, which is mostly a package outside the repository, and a call to a name with no binding in the file, which is a builtin or a global such as len, Error or new Map(), can never resolve locally, so the README's last column leaves both out of the denominator. That includes calls on values those imports produce, such as expect(x).toBe(y) from a test framework, and calls at the end of a field, element or return chain whose recorded type is a builtin (string, Array, Map, a Rust primitive, Vec or Option) or a type behind an unresolved import; a chain that ends on a type parameter stays unresolved, not external, unless the parameter is bounded. A call on a literal or on a local assigned from one (", ".join(..), rv = [], `a${b}`.trim()) is a call on str, list, string or Array, so it is external too, and in Go, Rust, Java and C#, which bind plain names without an import statement, a name that no indexed file of the language defines (new IllegalArgumentException(..), len(xs)) is a builtin or a standard-library name and counts as external rather than as a name with no match. A receiver whose annotation names a language builtin (string, Array, str, list) stays external even when the repository defines a function of that name, as zod does with its string() factory; a class or interface of that name still wins. osnova coverage prints both shares and the counts behind them. The unresolved remainder is mostly method calls on objects the syntax does not identify. osnova coverage reports these numbers for your own repository, per language and per reason, and osnova_plumb checks any list of call sites against the index so a claimed caller list can be verified before it is trusted.
Java and C# overloads share one qualified name, so the index keeps one symbol for the method and every overload's call edge targets it; warp on the method lists the callers of every overload. Each overload's declaration stays on the file card with parameters ({ min, max?, extension?, overrides?, access?, constructs?, types?, names? }: max is absent after a varargs or params parameter, a C# optional parameter widens max, extension marks a C# extension method, whose first argument may be written as the receiver, overrides marks a declaration written override in C# or annotated @Override in Java, and access is private for a method a derived type cannot call, which in C# includes one written without an access modifier in a class or struct, and package for a Java method written without one). A Java or C# call edge records its written argument count in arguments. A Java object creation is a call edge marked constructs: instance for new T(...), named by the type without its type arguments, and anonymous for new T(...) { ... }. A creation resolves only to a type, never to the constructor or another symbol that shares the type's name. The written name is scoped as javac scopes it: a member type an enclosing type declares or inherits (a supertype's member type is inherited unless it is private, or package-private in another package, as the member type's access records), then a top-level type of the file, a single-type import, the package, and the on-demand imports, with import declarations read from the code rather than from comments; a package-qualified name (new a.b.T()) names a type of that package; a local class of the name in an enclosing method (the index records no block scope), two local classes that share a qualified name, a name a static import could supply, and a name a supertype outside the index could supply as a member type stay unresolved, and a name none of these supplies is a library type and stays unresolved. instance then targets the type's constructors (parameters.constructs, which leaves out a method named like its class), so its argument count chooses among them as for a method, keeping the chosen line whenever another declaration shares the name. It targets the type itself when the type declares no constructor or is a record (primary, since a record's canonical constructor is written on its declaration); anonymous targets the type. Constructors are not inherited, so a creation never looks in base types. A creation qualified by an enclosing instance (a.new Inner()) names a member type of that instance's type, which the index does not follow, so it is a plain call without constructs. A C# creation keeps the name resolution of any call and carries no constructs, since its using directives, namespaces and type parameters decide which type it names. When the target's declarations in its file are more than one, or the one declaration cannot take that many arguments, the edge also carries overload: { line } names the start line of the one declaration that accepts the count, and { candidates } lists the start lines of every declaration that does when that is not exactly one, empty when none does. Counting arguments is syntax, not type inference: fromJson(json, String.class) against fromJson(String, Class<T>) and fromJson(String, Type) names both declarations in candidates. The count is also checked against the declarations of the same name in the other partial declarations of a C# type (a C# type written partial records its namespace and the generic arity of each enclosing type and itself as partial on its symbol, such as N.M1forBoxandN.M1.0 for Outer<T>.Inner, and its parts are the partial declarations with the same local name and the same value) and in each declared base class in turn, leaving out a base declaration the subclass cannot call; interfaces add none. A declaration marked overrides takes the place of one base declaration with the same parameter range instead of adding a choice. In Java the declaration hidden must also take the same parameter types, since Java overrides by signature and @Override also marks an interface method's implementation. types in parameters records each parameter type by the name it provably means from its own file: primitives as written, a single-type import or a java.lang type by its full name, a package-qualified name as written, any other simple name under the file's package, with dimensions written after the parameter name included. A type variable, a type nested in the same file, or a name a wildcard or static import could supply proves nothing, and then the method records no types and hides nothing. Same-named types imported from different packages therefore stay different. names lists, sorted, the simple names types read from the file's scope, because another file can still shadow them: a nested type that the declaring type or an enclosing type inherits shadows an import, a java.lang name or a same-package name, and a type of the same package shadows a java.lang name. A Java type symbol records supertypes, the number of supertypes its declaration writes, and interfaces, the written interfaces that name a local or imported type (heritage holds the superclass). A declaration's types hide a base declaration only when every supertype up its declaring type's chain and each enclosing type's chain is an indexed type that declares no nested type of those names, and no type of the package takes a java.lang name the types rely on; an enum, or a written supertype the index cannot follow (a qualified or external name), leaves the names unproven, and then the declaration hides nothing. When exactly one declaration in that set accepts the count and it lies outside the target's file, the edge moves to it: toSymbol and toFile name that declaration, the resolution basis stays the one that found the method, and overload is { line, from }, where from is the method the call resolved to before the move. When several do and some lie elsewhere, overload is { candidates, elsewhere } with elsewhere listing { file, line } for each of those, sorted by file then line; when an override hides one of several base declarations of the same range, all of them are listed, since which one it hides depends on parameter types. A Java base written as a simple name without an import is looked up among the member types each enclosing type declares or inherits, innermost first, and then among the top-level types of the same package, never in another package (an enclosing type with a supertype the index cannot follow leaves it unknown); a package-qualified base (extends q.Base) is followed as an import of that name would be. A base the index cannot identify, or a partial file that did not parse cleanly, stops the walk: a set that already holds two accepting declarations changes the edge as above, and otherwise a { line } chosen in the target's file becomes { candidates } with that line, since the unknown declarations may accept the count too. A target with a single declaration that accepts the count carries no overload and keeps that declaration even then: a base the index cannot see may still declare the overload the compiler binds. This limit is kept on purpose; withdrawing those edges too cost 10 recall points on humanizer and 1 on gson for one fewer false edge. obj.getAsJsonObject() on gson's JsonObject, which declares only getAsJsonObject(String), moves to JsonElement.getAsJsonObject(); humanizer's ordinalizer.Convert(2, "2") on a subclass that overrides Convert(long, string) beside the base's Convert(int, string) names no declaration. Warp prints the choice under each call site as overload: line N, chosen by argument count A (with ; moved from <qualified name> when the edge moved), overload: not determined; argument count A fits lines N, M (a declaration in another file as file:line) or overload: no declaration takes argument count A, and a callee answer (direction: out) gives the chosen overload's line as the callee's definition line.
The bundled C# grammar predates primary constructors on classes and structs (C# 12) and raw string literals (C# 11). When a C# file does not parse cleanly, it is parsed again with those spans left out: a primary constructor's parameter list and its base-type arguments, and the body of each raw string, keeping one quote at each end and any single-line interpolation hole without quotes or braces. Offsets are unchanged, so spans, signatures and line numbers come from the source. The second tree is kept unless it has at least as many errors over at least as much text, and the file is reported with syntax-errors only when the kept tree still has errors. Primary constructor parameters are not read, so they bind no receivers, and calls inside a left-out argument list or interpolation hole make no edges.
Coverage says how many call sites resolve; it does not say whether they resolve to the right definition. benchmarks/results/type-checker-oracle-2026-09-30.json scores that on six pinned checkouts against the language's own type checker or compiler, with the harness in benchmarks/oracle/. Every call expression is sent to the checker for the callee's declarations: pyright 1.1.414 through textDocument/definition on click, TypeScript 5.9.3 through checker.getSymbolAtLocation on zod, go/types (Go 1.27.1) on cobra, the javac 27 Compiler Tree API on gson, rust-analyzer 1.98.1 through textDocument/definition on ripgrep, and Roslyn 5.9.0's SemanticModel.GetSymbolInfo on humanizer, in compilations replayed from a real build. A site is in-repo, external or undecided by the checker's answer. An osnova call edge is true when the symbol span it names contains one of the checker's declaration lines in the same file, false when it contains none (including an in-repo target where the checker says the callee is external), and undecided when the checker had no verdict; undecided edges count in neither rate, and one line of tolerance absorbs multi-line call formatting. False-edge rate is false over decided; recall is distinct in-repo checker sites covered by at least one true edge. With this release's changes: click 2883 decided, 0 false, recall 90.4%; zod 21593 decided, 4 false (0.02%, the four sites of the 2026-09-21 record), recall 78.2%; cobra 1980 decided, 0 false, recall 87.5%; ripgrep 6066 decided, 29 false (0.48%), recall 85.8%; humanizer 7363 decided, 3 false (0.04%), recall 62.2%; gson 8133 decided, 4 false (0.05%), recall 72.3%. A Java or C# edge whose argument count fits several overloads or none names no declaration and is not claimed (overloadUndetermined: 2526 on gson, 602 on humanizer); an edge that names one overload is scored against that overload's span. At 0.11.0 every call named the last overload declared, a call sat at the first line of its call expression, and a C# file lost its declarations after a primary constructor or a raw string: gson had 2045 false edges (24.75%, 2026 of them overloads), humanizer 617 (8.25%) and ripgrep 112 (2.06%, 85 of them a chain call matched to a neighbouring call of the same name); the record keeps each corpus's 0.11.0 numbers in previous. The record classifies every false edge by cause. The unit key is (file, line, name): two calls of one name on a line share a verdict, and 2 of ripgrep's false edges, 3 of gson's and 1 of humanizer's are such shared keys where osnova's target is the checker's declaration for the other call. The rest name another function: on gson a new URL(...) resolved to a same-named constant and a receiver typed by its initializer; on ripgrep 11 functions declared once per #[cfg] branch, of which the checker sees the host's, a test module's function of the parent's name, a called closure or parameter, a function-local use and an external trait implementation; on humanizer a local function in top-level statements, which the index does not record. Each oracle sees one build configuration, stated per corpus in the record. The 2026-09-21 record holds the 0.8.0 numbers for click and zod and the 0.7.0 numbers before the shadowed-declaration refusal, when zod had 39 false edges.
plumb(index, symbol, claims, { direction, depth }) takes claims as { file, line } (parse path:line strings with parseClaims, which de-duplicates and rejects malformed input) and returns one verdict per claim: confirmed when a resolved call edge reached by walking the call graph from the symbol to the requested depth sits at that file and line (the line of the callee name, so a claim taken from the line of .method( in a multi-line chain matches); name-only when an unresolved or ambiguous call edge at that line names the target; no-call when the file is indexed and no call at that line names the target; not-indexed when the file is not in the index. missing lists resolved edges at the requested depth that no claim covers, sorted by file then line. Only call edges count; references and imports never confirm a claim. Limitations are exactly confirmed-means-indexed-resolved-edge-not-runtime-proof, name-only-is-a-heuristic-match, missing-covers-indexed-resolved-edges-only, call-edges-only. A bare name that matches several symbols throws an error naming the candidates, so a claim list is never silently discarded. Claim paths must be repository-relative: no absolute paths, drive letters, backslashes or parent segments. CLI plumb and MCP osnova_plumb print the same text under 4,096 code units (maximumPlumbCodeUnits); the MCP budget includes the generation prefix.
A reviewer, an agent or a commit message claims "these are all the callers". plumb checks the claim against the index instead of trusting it. Each claimed site is confirmed, name-only, no-call or not-indexed, and the resolved dependents the list left out are named. This is the click repository at the revision pinned in benchmarks/click-v1.json, with a claim that has two wrong lines and misses six:
osnova plumb "src/click/core.py#Context.invoke" --depth 2 \
--site src/click/core.py:934 --site src/click/core.py:1420 --site src/click/core.py:2000 \
--site src/click/decorators.py:93 --site src/click/decorators.py:200osnova plumb: src/click/core.py#Context.invoke, 3 confirmed, 0 name-only, 2 no-call, 0 not-indexed, 6 missing
claims:
confirmed src/click/core.py:934 -> src/click/core.py#Context.forward
confirmed src/click/core.py:1420 -> src/click/core.py#Command.invoke
no-call src/click/core.py:2000
confirmed src/click/decorators.py:93 -> src/click/decorators.py#make_pass_decorator.decorator.new_func
no-call src/click/decorators.py:200
missing:
src/click/core.py:1566 src/click/core.py#Command.main
src/click/core.py:2029 src/click/core.py#Group.invoke._process_result
src/click/core.py:2039 src/click/core.py#Group.invoke
src/click/core.py:2060 src/click/core.py#Group.invoke
src/click/core.py:2092 src/click/core.py#Group.invoke
src/click/decorators.py:119 src/click/decorators.py#pass_meta_key.decorator.new_func
confirmed means the index holds a resolved call edge at that line; it is not a runtime proof. missing covers indexed resolved edges only, so a call the index could not resolve, such as super().invoke(ctx), does not appear in either list; osnova_warp shows those as unresolved evidence with same-name candidates. Over MCP the same check is osnova_plumb with symbol, sites and depth.
Resolved share per corpus and language on the pinned checkouts, generated from the cited record (test/docs-coverage-table.test.ts fails when the rows and the record differ):
| Corpus | Language | Call sites | Resolved | Share | Excluding externals |
|---|---|---|---|---|---|
| click | python | 6593 | 2903 | 44.0% | 62.4% |
| click | all | 6593 | 2903 | 44.0% | 62.4% |
| cobra | go | 4374 | 1980 | 45.3% | 88.9% |
| cobra | all | 4374 | 1980 | 45.3% | 88.9% |
| gson | java | 23382 | 8473 | 36.2% | 56.7% |
| gson | all | 23382 | 8473 | 36.2% | 56.7% |
| humanizer | c_sharp | 28786 | 7654 | 26.6% | 52.4% |
| humanizer | javascript | 927 | 126 | 13.6% | 54.8% |
| humanizer | tsx | 120 | 14 | 11.7% | 23.3% |
| humanizer | typescript | 684 | 4 | 0.6% | 1.3% |
| humanizer | all | 30517 | 7798 | 25.6% | 51.3% |
| pyright | javascript | 32 | 0 | 0.0% | 0.0% |
| pyright | python | 11734 | 3375 | 28.8% | 67.3% |
| pyright | typescript | 46812 | 26695 | 57.0% | 75.5% |
| pyright | all | 58578 | 30070 | 51.3% | 74.5% |
| ripgrep | bash | 2 | 0 | 0.0% | 0.0% |
| ripgrep | ruby | 14 | 4 | 28.6% | 28.6% |
| ripgrep | rust | 13371 | 6117 | 45.8% | 71.7% |
| ripgrep | all | 13387 | 6121 | 45.7% | 71.6% |
| zod | javascript | 29 | 10 | 34.5% | 83.3% |
| zod | tsx | 150 | 16 | 10.7% | 18.2% |
| zod | typescript | 53238 | 21604 | 40.6% | 73.3% |
| zod | all | 53417 | 21630 | 40.5% | 73.2% |
testsFor(index, symbols, { limit, sitesPerFile }) maps symbol names or qualified names (a bare name that matches several definitions lists each one; an unknown name goes to unknownSymbols) to the indexed test files that reference them. A test file is one whose path matches the same pattern taskContext uses for candidate tests (test/, tests/, __tests__/, *.test.*, *.spec.*, *_test.go, test_*.py). Evidence is one of two bases: test-path-and-resolved-edge, a resolved call or reference edge from the test file into the symbol that is not a name heuristic, listed as sites with line, edge kind, resolution method and the enclosing test symbol; or test-path-and-file-import, a resolved import of the symbol's file by a test that has no direct edge to the symbol. A string that merely spells the symbol's name is not evidence. Files with a resolved edge sort before file-only imports, then by path; sites sort by line. limit caps test files per symbol (default 20) and sitesPerFile caps sites per file (default 10); both omissions are counted exactly. includeImportOnly (default true) set to false drops the test-path-and-file-import tier from the result entirely, so limit and omittedTests then count resolved-edge files only; the result echoes the setting as includeImportOnly.
The text output keeps the two tiers apart so an import-only file cannot be read as a test of the symbol. The header line and each symbol line carry separate counts, N test files with a resolved edge; M import the file only (or import-only files excluded), followed by any omission count. Resolved-edge files are listed under the heading resolved edge (calls or references the symbol):; each resolved-edge line adds ; in <name>, ... after its sites (before any ; +N more sites), naming the definitions in that file that make the listed calls, such as a pytest test_x or a TestCase method, so a runner can target them; a call inside an anonymous callback such as it("...", () => ...) or at file level has no enclosing definition and adds no name; when a symbol has none, the line no indexed test file has a resolved call or reference edge to <qualified name> replaces that heading. Import-only files follow under imports the file only (no indexed call or reference to the symbol):, which is omitted when there are none. Every line inside a tier still carries its own (resolved edge) or (imports the file only) label.
symbolsUnderTest(index, file, { limit, sitesPerSymbol }) is the reverse: the non-test symbols one file reaches through resolved direct call and reference edges (sorted by qualified name, sites by line, default 50 symbols and 10 sites each) and the non-test files it imports, plus the count of its unresolved edges, which are not listed. isTestPath says whether the file itself matches the test pattern; the query works on any indexed file. Limitations are exactly test-path-pattern-plus-indexed-edge, direct-edges-only, not-coverage, no-indexed-test-is-not-proof-of-no-test: a listed test references the symbol and does not prove coverage, and no indexed test is not proof that none exists, since unindexed files, dynamic calls and name-heuristic references are invisible. CLI tests <symbol...> [--no-import-only] and tests --file <path> and MCP osnova_tests (symbols or file, exactly one, plus limit and, with symbols, includeImportOnly) print the same text; MCP bounds it at 4,096 code units including the generation prefix.
unreferenced(index, { scope, kinds, limit, includeExported }) lists definitions that no resolved call, reference or extends edge reaches from outside their own body (an edge from the symbol itself or from one of its members does not count) in a non-test file, sorted by file, line and qualified name. Each candidate carries its exported flag (a TypeScript, JavaScript or Python export, or a member of an exported definition; other languages record no export metadata and every definition reads as not exported), unresolvedSameNameSites, the count of unresolved non-import edges in the same language family whose last name segment matches the symbol name (the nameMatches leads callersDetailed shows, and the sites a reader has to check by hand), testSites, the count of resolved edges from test files, and mentions, the count of identifier tokens equal to the name in non-test files outside the symbol's own span (null when the non-test text exceeds 32M code units and the scan was skipped; mentionsScanned says which). Entry points are never listed and are counted per rule in entryPoints: symbols named main, default exports, files named index.*, files named by package.json bin at the index root, test files, constructors (constructor, __init__; instantiation edges target the class, not the method), and Python dunders such as a module-level __getattr__ or a __repr__ method (the runtime calls them without a call site). The index records no decorator or framework-hook metadata, so decorated definitions are not excluded. Exported definitions are entry points for external consumers: they are counted in exportedNotListed and listed only with includeExported. A shadowed definition (a name its file declares in more than one scope, so the index keeps one record and can attribute no edge to it) is never listed and is counted in shadowedNotListed: its absence from the graph is not evidence. scope is a repo-relative path prefix, kinds selects the symbol kinds examined (default function, method, class, the kinds the index records edges to; constants, types, interfaces and enums receive no edges, so asking for them lists nearly every one), limit caps the list (default 50) with an exact omitted count, examined counts the symbols in scope of those kinds, and withoutLeads counts the listed candidates with no unresolved same-name site, no test site and no text mention (marked no leads in the text). A function passed as a value (a sort comparator or callback) is reached by a references edge in TypeScript, JavaScript and Python; in other languages, or through a member or property access, it has no edge and appears as a candidate whose text mentions are the lead to check. Limitations are exactly resolved-call-reference-and-extends-edges-only, default-kinds-function-method-class-because-other-kinds-receive-no-edges, no-indexed-caller-is-not-proof-of-no-caller, export-detection-typescript-javascript-python-only, no-decorator-or-framework-hook-metadata, text-mentions-are-identifier-tokens-not-references, shadowed-declarations-never-listed. The output ends with the notice that these are candidates only: dynamic calls, reflection, string references and external consumers are not indexed, so no indexed caller is not proof of no caller and never a deletion verdict. CLI unreferenced [--scope <prefix>] [--kinds a,b] [--exported] [-n N] and MCP osnova_unreferenced (scope, kinds, limit, includeExported) print the same text; MCP bounds it at 4,096 code units including the generation prefix.
benchmarks/exactness/exactness-v1.json lists hand-verified call-site sets (truth, as path:line) for symbols in pinned public checkouts, each with the scope, exclusions, extensions and the naive regex a person would type. scripts/exactness.mjs --workspace <name>=<checkout> ... --output <file> checks each checkout revision against its manifest, indexes it, runs the regex over the indexed text and callersDetailed at the case's depth, and records sites, precision, recall, false positives and misses for both. scripts/resolution-diff.mjs --base <ref> --head <ref> --corpus <path> [--dry] [--limit N] [--out file] builds osnova at two refs in temporary worktrees, indexes one corpus with each and lists every call edge whose resolution changed, the check the per-corpus totals hide (a commit can gain 28 sites and lose 10 and read as +18); with TYPESAFE_API_KEY set and without --dry it asks a System One model per changed edge which of the two targets the call site invokes, as a review aid that never touches the index. scripts/resolution-levers.mjs --corpus <path> [--corpus ...] [--per-reason N] [--dry] [--out file.json] is its companion for choosing the next lever: it indexes each corpus with this checkout's dist/, takes a stratified sample of the call edges that stay unresolved for a local reason (receiver-unresolved, no-matching-symbol, binding-blocked, bound-symbol-missing), asks the same model which lever would resolve each sampled edge (a field, return or parameter type, an unbounded generic, a value with no declaration, a callback, dynamic dispatch, or an external type) and, when the index holds same-name candidates, which one the call invokes, then ranks the levers by the call sites each would move, scaled by bucket size. It needs the same key, stops before asking without it, and every verdict is a sample estimate, never a measurement. Limitations are stated in the record: the truth sets are hand-verified, not compiler-proven; the regex is the first one a person types, not the best possible search; graph recall counts resolved call edges only.
The reason to keep a call graph instead of running a text search is not speed. It is that the first regex a person types is wrong more often than it looks, and nobody notices. Nine call-site sets on public checkouts in six languages were verified line by line after two independent agent runs and a manual review; the manifest is benchmarks/exactness/exactness-v1.json and scripts/exactness.mjs reproduces the README table from the pinned checkouts. Each cell shows sites found (precision / recall against the verified set).
What the text search got wrong: a comment that mentioned the method, Javadoc examples, a definition line, four calls split across lines (Configurator on one line, .GetFormatter( on the next), and same-named methods on other types: line_terminator on three builders and on the Matcher trait, beginObject on JsonWriter, getRawType on ParameterizedType and as a static helper on GsonTypes. What the graph missed: one receiver that comes out of a multi-value return in click, left unresolved rather than guessed. Reassigned receivers in Go, Rust, Java and C# resolve, since a name's static type cannot change in those languages, as do self inside a closure, a name taken out of an Option by if let, while let or a match arm, a type imported from another crate of the same Cargo workspace through its pub use, and a call on a bounded type parameter (M: Matcher, T extends Runner, [T Runner], where T : IRunner) or an impl Trait parameter, which resolves to the trait or interface method the compiler dispatches through. The graph never returned a site that was not a call of the target. The record is benchmarks/results/grep-vs-graph-2026-09-21.json.
await indexHealth(index) returns a state, all diagnostics, and a freshness report (or null when freshness cannot be checked). States are fresh, stale, partial, and unavailable. Disk changes take precedence over partial analysis in the state; diagnostics remain present in either case. Fresh means unchanged indexed inputs and no recorded extraction failures, not complete semantic understanding of every language or file.
Syntax-recovered files retain their text and recovered definitions with syntax-errors diagnostics. Extractor failures retain text with extraction-failed diagnostics. Missing grammars, unreadable ignore files, directories, file stats or file contents stop indexing/refresh rather than silently removing data. Operational failures use IndexingError with a structured diagnostic and the underlying error as cause.
CLI queries emit detailed partial-analysis warnings on stderr, and osnova coverage also lists files skipped for size on stdout beside the shares they qualify. Ordinary MCP query results use one deterministic line that groups diagnostics by phase/code (at most four categories plus an omitted-category count, with scan/file-too-large always first so a file missing from the index is never folded into that count) without repeating per-file paths, and the line ends by naming the cause: files above the size cap not indexed, files that did not parse fully, or results may be incomplete. osnova_outline adds one line naming the requested file's own diagnostic. Generation identity and incomplete-analysis state remain explicit. Full diagnostic paths remain available through doctor, indexHealth and CLI checks. Map cards keep their compact health indication inside the existing code-unit cap. osnova check exits 1 for stale, partial, or unavailable indexes, and 0 only for fresh indexes. Full builds may save partial indexes so text search and recovered definitions remain available.
Artifact format 9 stores four files per workspace: index.json (structural core with file-path and symbol-name tables), index.sha (SHA-256 of the raw core bytes, verified before parsing; the verified checksum is the index generation), edges.json (one interned integer tuple per edge, read and hash-verified with the core, decoded on the first edge query) and text.bin (source text read lazily per file and verified against its recorded hash). The core records each symbol's incoming and outgoing edge counts beside its symbols, so text search and the bounded skeleton rank by degree without decoding the edge section. A refresh reads index.sha and the verification sidecar, then scans and compares, and only then loads the core; an unchanged refresh leaves the verification sidecar untouched. A load verifies the core checksum and parses only the envelope (format, extraction version, root, section identities); the file and symbol tables are decoded and validated on the first files, symbols or edge access, and a checksum-valid core whose body fails validation reports cache-read-failed there rather than at load. A publish copies unchanged text byte ranges from the previous sidecar. loadIndex returns undefined for format-1 through format-8 caches; query commands rebuild them. A missing or mismatched section is reported as cache-read-failed, never partially trusted. Corrupt or unsupported newer artifacts and failed cache writes remain explicit errors. Repaired files clear their old diagnostics on incremental update.
Cache location: explicit cacheDir parameter, else OSNOVA_CACHE_DIR, else the platform default (macOS ~/Library/Caches/osnova/, Linux $XDG_CACHE_HOME/osnova/, Windows %LOCALAPPDATA%/osnova/cache/). One subdirectory per workspace, LRU-evicted across workspaces past 32 workspaces or 256 MB (CachePolicy.maxWorkspaces, maxBytes). A process that loads an artifact leaves a lease (readers/<pid>.json in the workspace directory), because it reads the text and edge sidecars lazily after the lock is released; eviction spares a workspace whose lease names a live process on this host, removes leases of processes that have exited, and treats a lease from another host as live. A cache whose every workspace is in use can therefore sit above its caps until a reader exits. Extraction of a full build runs on a pool of worker threads (min(availableParallelism - 1, 8)) once the workspace has at least 32 files, and a refresh uses the same pool only when at least 64 files changed (below that, worker startup costs more than parsing the changed files on the main thread); OSNOVA_EXTRACT_WORKERS=0 keeps it on the main thread and OSNOVA_EXTRACT_WORKERS=<n> fixes the pool size. The pool ends with the build, results merge in path order, and the artifact is byte-identical either way.
Git worktrees of one repository share a cache family. The family id is the resolved git rev-parse --git-common-dir of a workspace that is the top level of a main or linked worktree; it is resolved once on the first build (never per refresh, and git missing means no family) and stored beside the artifact in the family.json sidecar, not in the artifact. Every worktree keeps its own cache subdirectory, lock and artifact, keyed by its own path. When a workspace with a family has no cache yet, buildIndex and refreshWorkspace look for a sibling cache in the same family whose receipts are intact (index.sha matching a valid verification.json, core checksum, text and edge sidecars verified), copy its text.bin and edges.json into the new workspace directory under both locks (the sibling lock is not waited for), re-root the sibling core in memory and then run the ordinary changed-file refresh, so the published artifact is byte for byte what a cold build writes. onProgress reports { phase: "seed", done: <files reused>, total: <sibling files>, sibling } and osnova build prints seeded from sibling worktree cache <root>: N of M files reused. OSNOVA_CACHE_SEED=0 or WorkspaceOptions.seedFromSiblings: false disables seeding; osnova doctor reports the family and its sibling caches as cache:family.
refreshWorkspace coordinates refreshes per canonical workspace/cache identity in-process and across processes. It publishes one coherent artifact generation, verifies source stability before returning, and exposes indexGeneration plus evidenceFingerprint for source-hash receipts. Defaults: 32 workspace artifacts (defaultLruCap), 256 MiB artifact budget, 10-second lock wait and 25 ms polling. Owners are checked for verified local process exit; malformed, foreign-host or otherwise unverified locks fail closed rather than being stolen. This is bounded source verification, not an atomic filesystem snapshot.
osnova mcp --watch (or createOsnovaMcpServer(root, { watch: true | { debounceMs, maxStaleMs } })) keeps a recursive fs.watch on the workspace. A change outside ignored directories and the cache marks the index stale and schedules a refresh after debounceMs (default 200 ms); a query reuses the last verified index while no change has been seen and the verification is younger than maxStaleMs (default 30 s), and otherwise verifies the tree as it would without a watcher. If the platform refuses a recursive watch the server says so on stderr and refreshes per query. status() on the created server reports watching, refreshes, pendingChanges and warm.
osnova mcp starts its first refresh at launch rather than on the first tool call, and after each refresh that publishes a new index it warms the ranking corpus used by osnova_ground and osnova_footing and footing's edge maps. It yields to the event loop between files once 20 ms have passed, but one file, the final join of the corpus and the edge maps each run in one step, about 0.5 s and 1 s on an 18,425-file repository; any request that arrives during such a step waits for it, even one for a tool that needs neither. A newer index or close() cancels the warm-up, and none starts after close. A newer index cancels the old warm-up, and a call that arrives first builds what is missing itself, so answers never depend on the warm-up. osnova mcp --no-prewarm keeps the launch refresh but skips the warm-up, for hosts short on memory (on an 18,425-file repository the warm-up raised peak memory by about 200 MB, 5%); createOsnovaMcpServer(root, { prewarm: true }) turns the warm-up on for an embedded server; it is off by default there, and status().warm reports off, idle, warming, warm or closed. A watcher can miss events on some file systems; the staleness bound and the generation receipt on every response keep that visible.
reuseMemory: true lets a trusted long-lived host such as the bundled MCP server reuse an immutable loaded index while the atomically published artifact's device/inode/size/mtime/ctime signature remains unchanged. External publication, corruption or deletion invalidates memory before use. The public default is false because JavaScript consumers can cast away readonly types and mutate returned maps; ordinary callers receive a fresh loaded object.
Nested .gitignore and .osnovaignore rules are applied by directory with negation support. Runtime Osnova cache directories inside a workspace are always excluded. Cache artifacts carry envelope/content checksums and extraction-version identity; text, size, line count and source hashes are validated on load. Access metadata drives LRU eviction, with count and artifact-byte caps. Sidecars not owned by the core artifact lifecycle are preserved.
Successful full verification writes a generation-bound metadata sidecar with file size, nanosecond mtime/ctime, inode and device. Subsequent workspace refreshes can skip content reads when every field and the artifact generation still match; any path/metadata change hashes affected files, while missing/corrupt/mismatched sidecars fall back to full hashing. Public freshness() always hashes content. Structural generation IDs are cached from exact serialized bytes.
Large cache artifacts use deterministic level-1 gzip to favor edited-refresh latency over maximum compression. On the pinned 61 MB logical artifact used for profiling, level 1 compressed in 153 ms versus 497 ms at the previous default level, while increasing stored size from 6.7 MB to 8.7 MB. Cache byte limits continue to apply to the stored payload.
Scanning applies root and nested .gitignore plus optional .osnovaignore rules with scoped negation, skips dotfiles and configured output/dependency directories, and excludes files above 1 MB. Binary or non-UTF8 files get fallback cards with source hashes and empty text rather than searchable contents.
Node.js 22.13 or newer.
npm install -g @getdomovoi/osnova
osnova build . # index the repository (cached, incremental after this)
osnova ground "where do we validate tokens"
osnova warp src/auth.ts#verify # who calls it
osnova groundwork # directory clusters, hubs, hotspotsOne global install serves every repository and every agent. osnova mcp with no --workspace uses the directory the client starts it in, and MCP clients start servers in the project root. So each client needs one entry, in its own global config, and nothing per project. Osnova never writes inside your repository and never touches another client's configuration.
Claude Code:
claude mcp add --scope user osnova -- osnova mcpCodex, in ~/.codex/config.toml:
[mcp_servers.osnova]
command = "osnova"
args = ["mcp"]OpenCode, in ~/.config/opencode/opencode.json:
{ "mcp": { "osnova": { "type": "local", "command": ["osnova", "mcp"], "enabled": true } } }osnova setup claude --apply and osnova setup agents --apply apply a whole family at once, as described in the README; the per-client commands below remain for one piece at a time. --uninstall reverses a family, previewing unless --apply is given: it cuts the top-level osnova MCP entry out of each config's text with its comma (Codex: the [mcp_servers.osnova] table and its [mcp_servers.osnova.tools.*] tables), so comments and every other key keep their bytes; removes osnova's own hooks, and any group or event they leave empty; deletes the plugin, extension and skill files osnova installed, and the skill's folder once empty; and, with --instructions <file>, removes the block between the osnova markers. Anything that is not osnova's own or was changed since it was installed is kept and reported instead of stopping the run: an osnova MCP entry that launches something else, more than one osnova key in the same object or more than one MCP root object, osnova run inside a shell command, a plugin or skill file that differs from the shipped one, an instructions block edited since setup, a configuration, plugin or skill file or folder reached through a link, an instructions file that is itself a link (pass the file it points to), and, with --only, the shared skill while an installed harness outside the list still reads it. A per-project entry in ~/.claude.json is never touched, and a comment directly above the next entry or table stays. Every edited or deleted file is backed up first as <file>.bak-osnova-<stamp> (a skill's backup moves beside its folder, as osnova-SKILL.md.bak-osnova-<stamp>). When each configuration file already held its MCP object (mcpServers, mcp or the Codex tables) and ends with a newline, setup --apply then --uninstall --apply leaves it byte-identical, CRLF line endings included; a file or object setup created is left with its empty structure. If a step fails part way, the changes already made are printed with their backups before the error. One command applies all of it for Claude Code: osnova setup --apply --client claude-code --hooks writes the MCP entry to ~/.claude.json and the three hook groups to ~/.claude/settings.json, backing up each file it changes as <file>.bak-osnova-<stamp>, and does nothing on a second run. --hooks reconciles the hook file with this install rather than only adding to it: an existing osnova hook is repointed at this command, keeping everything from hook <name> onward and the entry's timeout and matcher; an osnova hook this version cannot run (say hook gate after moving to a release without it), a duplicate, or a proposed hook under the wrong event is removed; and a shell command that may run an osnova hook (a shell's -c script with a segment that runs osnova's own launch followed by hook <name>, such as bash -c "cd ~ && node .../dist/bin.js hook prompt") is left as written; since what a script runs cannot be checked, it does not count as installed, the plain hook is added beside it, and the notice names the command. Hooks that are not osnova's stay untouched, even inside a group they share with one. An existing top-level osnova MCP entry that launches osnova (a part before mcp names osnova, such as a path to another install) is repointed the same way, keeping the flags after mcp, keys such as env and Codex's [mcp_servers.osnova.tools.*] tables; a per-project entry in ~/.claude.json is never touched. --preview prints the same diffs without writing, and an osnova entry that does not launch osnova is a conflict that stops the whole apply. --instructions AGENTS.md appends a short block once between <!-- osnova:start --> and <!-- osnova:end --> markers: a pointer to the tools and the two reading rules, since the MCP server's instructions already carry the tool list. osnova doctor then checks that every configured hook and MCP command reports this osnova's version, and that each installed plugin or skill file matches the one this osnova ships. A hook or MCP entry counts as osnova's only in a form that runs osnova's own program, where a path counts only when it exists and lies inside a package whose package.json names @getdomovoi/osnova (checked on disk, never by name): the bare osnova command or such a path alone; node, nodejs or bun running such a path; or npx, bunx, pnpx or pnpm dlx running the scoped @getdomovoi/osnova package; with only plain flags between them (-y, --yes, --quiet, --enable-source-maps, --no-warnings, a memory or stack size). A user's own script under a folder named osnova, a project script (pnpm osnova), an unrelated package (npx osnova), a command that only mentions osnova (echo osnova mcp) or evaluates code (node -e osnova) is never changed.
Measured on Claude Code with blast-radius tasks that name their symbol, the hooks did not cut turns or cost against the MCP server alone, which already carries the contract as MCP instructions; they pay on prompts that name no symbol and on editing turns. Claude Code hooks, so the graph speaks first without a tool call: osnova hook session prints one line when a session starts, the index size and a pointer to the tools (the MCP instructions already carry the contract; --full-contract restates it for a harness without MCP), and osnova hook prompt prints up to eight starting points (the definitions the prompt names with exact file:line, plus one line counting the related definitions and relationships it leaves to osnova_footing and osnova_warp; no relationship lines, since the callees are in the body the agent reads next, all under 1,024 code units) on every prompt. Both read the hook payload on stdin, never write to the repository, and print nothing on a slash command, a short prompt, or a failure. osnova hook stop runs when the agent is about to finish: it diffs the worktree against HEAD and hands back the indexed dependents of the changed symbols; it continues the turn at most once per diff per session, and only when more than OSNOVA_HOOK_SETTLE_BLOCK_AT dependents (default 1) lie outside the change, through hookSpecificOutput.additionalContext on Claude Code, decision: "block" on Codex and followup_message on Cursor, and otherwise warns the user through systemMessage without continuing. On a repository with no cache the session hook starts the build in the background, waits up to three seconds for it, so a small repository has starting points from its first prompt, and otherwise the other hooks stay quiet until the cache exists; osnova mcp waits up to two minutes for such a build before its first answer; a dead owner is reclaimed at once, but a stuck or unverifiable one holds the call until that deadline. The workspace is the git top level of the client's directory. The prompt hook seeds only from names the prompt spells as code, a backticked token or an identifier with an inner capital, underscore or digit, so a prose word that happens to be a symbol name, such as load or within, prints nothing. A file the prompt names by path or file name (claude-settings.js, scripts/claude-settings.js, or an absolute path) adds a - file <path>: <n> symbols; osnova_outline for its shape line when it matches an indexed file at a folder boundary; a file name shared by more than four indexed files is skipped as too ambiguous. osnova hook tool is an opt-in PostToolUse hook (osnova setup --apply --hooks --nudge, or osnova hook install-preview --nudge): after a Grep call or a Bash grep or rg whose pattern is one identifier or method name that the index knows with resolved callers, it adds one line with the resolved call-site count, the file count and the osnova_warp call that lists them, once per name per session and nothing otherwise. Both the once-per-name and once-per-diff state live under the cache directory as hook-state/<session id>.json, never in the repository or the system temporary directory. Measured headless on the same blast-radius tasks, it fired as designed and changed nothing: the model's greps come after its first osnova_warp call, as confirmation reads, and a line that arrives after the grep does not remove them (Bash calls 38 against 39, cost 5 percent higher, inside run noise). It is not in the default hook set. osnova hook install-preview prints the settings snippet and writes nothing; osnova setup claude --apply writes the same hooks into ~/.claude/settings.json, backing the file up first.
osnova hook gate is the opt-in search gate (osnova setup --apply --hooks --gate, osnova setup claude --gate, osnova setup agents --gate), the one hook that can stop a tool call. It reads the call by shape rather than by tool name: a command or cmd field, a string or an argv list, is a shell command, split into pipeline stages outside quotes; a stage that opens a pipeline (not one after | or |&) and runs grep, egrep, fgrep, rg, ag, ack, fd, find or git grep is a search of its path operands by that tool's own grammar (find's paths before its expression; for the others, the operands after the pattern, or all of them when an option gives the pattern or a list-only mode such as rg --files, ag -g or ack -f needs none, with each tool's own value options skipped), else of its folder after any cd; shell keywords (if, then, do, ! and the like) are read through; a ( … ) subshell restores the folder when it closes, a shell run with -c (bash -lc 'rg …', also as an argv list) is read for the command it runs, and a call's own workdir or cwd field sets where it starts; $NAME and ${NAME} expand from the command's own NAME=value assignments, and a path or cd that still holds an unknown variable targets nothing, so the call runs; a tool named grep, glob, search, find, rg, ripgrep, codebase_search or file_search searches its path fields, limited by its glob or include field (and by pattern for glob and find). A search is gated when a target reaches an indexed file in a code language, matching the limit if one is given; data, prose and configuration files kept as text never count, nor does a path outside the workspace or a stage after |. An osnova MCP tool under any prefix (mcp__osnova__osnova_ground, osnova_osnova_ground, Cursor's bare name with mcp_server_name), an MCP proxy call whose arguments name an osnova_* tool, or a shell command that runs the osnova CLI, directly or through npx, bunx, pnpx, pnpm exec, pnpm dlx, yarn exec, bun x or a runtime given the CLI's own script (node …/osnova/dist/bin.js, …/node_modules/.bin/osnova), counts as using osnova; another script in a folder named osnova does not, nor does a grep for the word. The gate denies a gated search until osnova has been used in the current turn; the prompt hook advances the turn for a session the gate already tracks, a plugin sends hook_event_name: "UserPromptSubmit", and Cursor, which sends its hooks no prompt event, starts a turn on each new generation_id. With --adaptive (Codex, whose hooks may not see MCP calls, and the Pi extension, whose MCP adapter names may differ) it denies only the first gated search of a turn until the session has shown one osnova call, then holds as in the default mode, so a harness that never reports osnova calls is never locked out. The deny is hookSpecificOutput.permissionDecision: "deny" with the reason on Claude Code and Codex, {"permission":"deny","user_message","agent_message"} on Cursor, a thrown error from tool.execute.before in the OpenCode and Kilo gate plugin (osnova-gate.js; checked live on Kilo 7.8.18, where the model reads the reason as the tool's error), and { block: true, reason } from the Pi gate extension's tool_call handler (osnova-gate.ts). OpenCode 2.x loads neither plugin: its plugin API has no message or tool hook. Every failure, an unknown payload, a missing session id or a workspace without a cache lets the call through. OSNOVA_GATE=off switches it off. Its state lives under the cache directory apart from the nudge and stop state: hook-state/gate/<session id>.json holds the turn counter, the last denied turn and Cursor's generation, and hook-state/osnova/<session id>.json the turn of the last osnova call, a file only an osnova call writes, so a search decided in parallel cannot erase it. Each folder holds one kind, so no session id can name another session's file, and every hook state file is written to a temporary file and renamed into place.
Setup replaces an installed skill, plugin or extension file that is byte-for-byte a version an earlier osnova shipped, backing it up first, so an upgrade carries the new file; src/diagnostics/shipped-history.ts lists the SHA-256 of every earlier version, with line endings normalized, and test/shipped-history.test.ts checks the list against git history. A file that matches no shipped version was edited by its owner and is kept and reported, as before; --uninstall deletes a file that matches the current or an earlier shipped version.
Other harnesses get the same three levers by their own means. osnova setup --apply --client codex --hooks writes ~/.codex/hooks.json with the same session, prompt and stop hooks (Codex reads the hookSpecificOutput JSON it validates). Codex skips a new or changed hook until you trust it: after the apply, open /hooks in Codex and trust the three osnova entries, or they are skipped without a message. --client cursor --hooks writes ~/.cursor/hooks.json with the stop hook as a follow-up message, since Cursor's prompt hook cannot add context. --client opencode --plugin and --client kilo --plugin copy the shipped plugin into the client's plugins/ directory: it appends starting points to each user message by calling osnova hook. It does not restate the tool contract, because OpenCode and Kilo already place the MCP server's instructions in the system prompt. --client pi --plugin copies the shipped extension into ~/.pi/agent/extensions/, which does the same through before_agent_start. Every MCP client also receives the contract as the server's instructions on initialize, so a client without hooks or plugins still sees it. osnova setup --apply --skill copies the shipped Claude Code skill to ~/.claude/skills/osnova/SKILL.md: a short order of work (footing, then warp, plumb any claimed list, settle before finishing) that Claude Code loads only when a task matches its description, so it costs nothing on other prompts. The file is never overwritten once present. Measured on the same blast-radius tasks with Claude Code headless: when the prompt names the MCP server the skill is never opened, and when the prompt says nothing about it the skill is opened first in three of four runs, the arm answers four of four perfectly against three of four without it, and costs 14 percent more, most of it the checks the skill asks for. It is a discipline for longer tasks, not a saving.
Pi, through the pi-mcp-adapter extension, in ~/.pi/agent/mcp.json:
{ "mcpServers": { "osnova": { "command": "osnova", "args": ["mcp"] } } }Kilo, in ~/.config/kilo/kilo.jsonc:
{ "mcp": { "osnova": { "type": "local", "command": ["osnova", "mcp"], "enabled": true } } }Cursor, in ~/.cursor/mcp.json, and any other client that takes the common mcpServers shape:
{ "mcpServers": { "osnova": { "command": "osnova", "args": ["mcp"] } } }No global install? Replace osnova with npx -y @getdomovoi/osnova in any of the above. Pin a workspace with osnova mcp --workspace /path/to/repo when the client does not start in the project root.
Not sure what your config looks like after the change? Ask for a diff:
osnova setup --preview --client codexIt reads the client's real config file, proposes the one entry as a unified diff, and stops. Nothing is written. Other entries, comments and formatting stay as they are. If an osnova entry already exists it says so instead of proposing anything. Clients: claude-code, codex, opencode, kilo, cursor, pi. Add --command npx --command -y --command @getdomovoi/osnova for the no-install form.
osnova doctor checks the runtime, the cache and every packaged grammar, and prints a readable report: the checks that are not ok with their messages, the 21 languages grouped by support tier (syntax with binding and receiver hints; syntax with name heuristics; tags query with name heuristics), and what a green grammar check proves, which is that the grammar loads and parses a short synthetic snippet, not that every real file parses. --json prints the full report, including each language's limitations.
The same wiring ships as a Claude Code plugin at integrations/claude-code/ (.claude-plugin/plugin.json, .mcp.json, hooks/hooks.json and the skill), listed by the marketplace manifest at .claude-plugin/marketplace.json, so /plugin marketplace add getdomovoi/osnova followed by /plugin install osnova@osnova installs the MCP entry, the three hooks and the skill together, each command run as npx -y @getdomovoi/osnova@<version>, pinned to the plugin's release because the plugin directory rejects an unpinned launcher, which fetches that version on first use and then runs from the npm cache. test/distribution-manifests.test.ts holds the plugin hooks to exactly what osnova setup writes, requires the plugin's launchers and its README.md to name the package version, and pins every manifest version, including server.json for the MCP registry (io.github.getdomovoi/osnova, the mcpName in package.json), to the package version, and validates server.json against the registry schema it names, vendored at test/fixtures/schemas/. The plugin writes nothing inside the repository; hook state and the index live under the cache directory as before. For the Claude plugin directory, which blocks this repository's pnpm-workspace.yaml, .github/workflows/plugin-sync.yml copies the plugin folder, LICENSE and NOTICE to https://github.com/getdomovoi/osnova-claude-plugin on every push to main that changes them, through scripts/sync-claude-plugin.sh and a deploy key that can write only to that repository (CLAUDE_PLUGIN_DEPLOY_KEY).
osnova build <root> # build and cache the index
osnova ground "<question>" # keyword search with exact file:line hits (--lean drops the source, --scoped ranks per package)
osnova thread "<pattern>" # regex or literal search grouped by symbol
osnova outline <file> # every definition's signature and span
osnova warp <symbol> # direct or transitive callers or callees
osnova groundwork # directory clusters, hubs, hotspots
osnova footing "<question>" [-n <n>] [--depth <n>] [--max-code-units <n>] # task context as JSON
osnova settle --base-ref <ref> # dependents of the symbols changed since a git commit (--base-cache compares two preserved indexes)
osnova plumb <symbol> --site <path:line> ... # check claimed call sites against the index
osnova coverage [--json] # call-site resolution coverage per language and reason; lists files skipped for size
osnova tests <symbol...> # test files that reference a symbol (--file <path> inverts it)
osnova unreferenced # definitions with no indexed caller; candidates, never proof
osnova check <root> # staleness gate for CI (exit 1 when stale)
osnova doctor [--json] # read-only runtime, cache and grammar checks; readable by default
osnova setup <claude|agents> [--apply] [--only <harnesses>] [--gate] # one harness family; previews unless --apply; --gate adds the opt-in search gate
osnova setup --preview --client <name> # diff for one client's config; never applies
osnova hook <prompt|session|stop|tool|gate|install-preview> # editor hooks; payload on stdin
osnova mcp [--workspace <path>] [--watch] [--no-prewarm] [--lsp-server <absolute path> --lsp-languages <list> [--lsp-arg=<arg>]... [--lsp-timeout-ms <n>]] # MCP stdio server; --watch refreshes on file change instead of per query; --no-prewarm skips the warm-up; --lsp-server adds a language server's references to osnova_warp, osnova_plumb, osnova_settle and osnova_tests
osnova update-check [--json] # the only command that opens a network connectionLocally, osnova settle --base-ref <ref> compares the working tree with any commit: it exports the commit's tree with git archive into the cache directory (no checkout, no worktree), indexes it there once per commit (the two most recent base trees per workspace are kept), takes git diff <ref> as the changed spans and lists every indexed dependent of the changed symbols. Over MCP the same comparison is osnova_settle with baseRef, and a call with neither baseRef nor diff uses HEAD; a diff without baseRef compares against the current index only. It fails closed when git is missing, the ref is unknown or the workspace is not a git repository.
The same check runs on every pull request without an agent. The action runs osnova settle --base-ref against the pull request base, then lists every indexed dependent of the symbols the pull request changed in the job summary, and as a comment when asked:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: getdomovoi/[email protected]
with:
depth: "2"Inputs: base-ref (default: the pull request base), depth, workspace, version (the npm version run through npx; by default the version of the action ref, so @v0.8.1 runs osnova 0.8.1, and latest floats on purpose), command (run a local build instead), comment (post a PR comment; needs GH_TOKEN with pull-requests write). Output: report, the path of the report file, for a workflow that posts or uploads it itself. The report is indexed structural evidence only: a missing dependent is not proof that nothing depends on the change. scripts/settle-ci.sh is the whole action and runs by hand with BASE_REF=<commit> bash scripts/settle-ci.sh.
pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm perf
pnpm check:package
pnpm test:package
pnpm test:installThe perf script enforces first-build and incremental-refresh budgets on a generated fixture repo. Tests include per-language extraction goldens, an incremental-equals-full property test over randomized edit sequences, CLI round-trips, and MCP handshake plus tool round-trips over an in-memory transport. The bundled bash grammar throws resolved is not a function from its external scanner on a case statement or a [[ ]] test, so a shell file that contains either is recorded with the extraction-failed diagnostic and no symbols; the parser is discarded and the next file parses cleanly, and plain if [ ], loops, functions, heredocs and arithmetic parse. The bundled tree-sitter-lua.wasm is deliberately not registered: with web-tree-sitter 0.25.10 and tree-sitter-wasms 0.1.13 its second parse in a process yields spurious ERROR and MISSING nodes on valid input, whatever parser, language instance or worker thread is used, and test/grammar.test.ts keeps the reproduction as a skipped test until a grammar bundle passes it.
doctor is read-only: it checks runtime, workspace/cache access and all packaged grammar assets without scanning source or writing probes. Its capability matrix states where binding/receiver hints exist and where only name heuristics remain. previewSetup(client, { home, configPath, command }) reads one client's global config (never a symlink, never above 1 MiB, always inside the home directory), inserts the osnova entry textually so other entries, comments and formatting survive, and returns the merged text, a unified diff and one of create, append, unchanged or conflict. It never writes.
Package smoke validation packs the artifact, extracts it outside the checkout, verifies every export/declaration/shebang, loads all twenty-one grammars, executes lifecycle/retrieval/doctor APIs, and drives a real stdio MCP child through initialization, all ten tools, refresh and EOF shutdown while rejecting stdout contamination. test:package reuses locally installed dependency targets without downloads; test:install performs a fresh registry-backed dependency install with install scripts disabled, then runs the same consumer checks. Linux/Windows execution runs in CI.
configureLspEnrichment, loadLspEnrichment, and refreshLspEnrichment provide an opt-in sidecar for explicitly approved local language-server executables. Configuration/load do not launch processes; refresh requires enabled: true, current source hashes and zero-based UTF-16 query positions. Multiple matching servers and languages are dispatched independently, so one installed server cannot shadow another.
osnova mcp --lsp-server <absolute path> --lsp-languages <list> names one language server on the command line that starts the MCP server; --lsp-arg=<arg> passes each server argument (use the = form for arguments that start with -) and --lsp-timeout-ms sets its request timeout (default 10,000, at most 60,000). For a callers question (osnova_warp, direction in) on a symbol in one of those languages, the server is asked for textDocument/references at the symbol's name, and the answer gains a section after the graph answer (unchanged, except that a full: true answer that would reach the 16,384-code-unit cap is clipped earlier by the section's length): language server (textDocument/references, not syntax edges): N locations: declaration …, resolved above …, confirmed unresolved leads …, not in the graph …, followed by the listed lines. A location on a line the graph already lists counts as resolved above; one on the line of an unresolved same-name lead in the answer confirms that lead; the graph stores no column, so a line holding both confirms nothing and its locations count as resolved above. Call edges sit at the line of the callee name, where the server reports it; an edge anchored one line away, such as a decorator route above the method it registers or a registration whose handler argument sits on the next line, may match a neighbouring listed line once. The queried position, and a location written as a declaration of the name (an overload signature, def, class, const and the like), count as declarations; a recursive call on the declaration line counts as a call. The section has its own 1,024-code-unit budget with an exact count of lines it leaves out. One server session serves the MCP server's lifetime: it opens every indexed file in its languages (at most 4,096 files and 64 MiB of source, plus the queried file when it falls outside those limits; the section says when the server was given fewer), restarts when the index generation changes or after any failure, and closes a server that is still starting when the MCP server closes. A new session repeats each request until two answers agree; a settled one repeats once and returns to that loop when the two differ, because a later symbol may sit in a project the server has not loaded. Repeats stop at the request timeout, and the section says when the answer never settled. A failed or timed-out request adds one unavailable line and leaves the graph answer intact. The server runs with its home and temporary directories inside the cache, but it is not sandboxed and reads the workspace like any program you run. On zod, the first warp answer of a session took about 3 s and later ones 40 to 250 ms.
The same session checks a callers claim (osnova_plumb, direction in, any depth) on a symbol in the server's languages. The claim verdicts and missing list are unchanged, and a section follows them: language server (textDocument/references, not syntax edges): N locations: declaration …, on claimed sites …, on missing sites above …, elsewhere …; the server confirms X of K claims (graph confirmed …, name-only …, no-call …, not-indexed …). It lists the claims the server confirms that the graph did not confirm, with the graph's verdict, and the locations on neither a claimed site nor a missing site: sites the claim left out that the graph does not list as missing, marked (graph: name-only) when the graph holds a same-name call on that line. Only a location on the claimed line itself confirms a claim, since a claimed line may hold no call; a location next to it is listed where the server put it. Locations are matched to missing lines as in osnova_warp, including the one neighbouring-line match. Server references are direct, so a depth-2 claim is checked only at depth 1. The section has its own 1,024-code-unit budget after the plumb answer's 4,096 and an exact count of lines it leaves out; a failure adds one unavailable line.
osnova_settle asks the same session about the changed symbols with a current definition in the server's languages, at most 8 per call, the ones with the most resolved graph dependents first and then by qualified name, all under one request timeout for the whole call. That timeout starts with the call and also bounds its wait behind other requests to the session and any server start-up; a symbol whose request was not sent before it ends counts as past the deadline, and a start-up or shutdown already under way finishes for the next call without holding this one. The impact answer is unchanged, and a section follows it: language server (textDocument/references, not syntax edges): asked about Q of E changed symbols in its languages (not asked: … over the cap of 8, … past the deadline, … after a failure); N locations: declaration …, inside changed symbols …, among the dependents above …, not among them …, then, per symbol, the locations not among the dependents. A location is among the dependents when the definition the graph attributes an edge on its line to (the file, for module-level code) is a listed current dependent, or else when its innermost enclosing definition (or, at top level, its file) is one; the same test against the changed symbols counts it as inside a changed symbol. A failed request stops the call: the symbols after it are counted, not asked, and each unavailable answer is listed with its code. The section has its own 1,024-code-unit budget after the settle answer's 4,096 and an exact count of lines it leaves out.
osnova_tests with symbols asks the same session about the symbols it found in the server's languages, in qualified-name order and under the same cap of 8 and one request timeout per call; file mode asks nothing. The two tiers are unchanged, and a section follows them: language server (textDocument/references, not syntax edges): asked about Q of E symbols in its languages (not asked: …); N locations: declaration …, outside test files …, in resolved-edge test files above …, in import-only test files above …, in other test files …, then a third tier per symbol, test files neither tier lists, by the language server, with each file's reference lines. Test files are the ones the tiers use, and a file counts as held by a tier even when the tier's limit did not show it; with includeImportOnly: false an import-only file is not held and can appear in the third tier. The section has its own 1,024-code-unit budget after the tests answer's 4,096 and an exact count of lines it leaves out.
Evidence remains separate from structural edges and is labeled source: "lsp", claim: "server-locations", with launch identity, source hashes, workspace fingerprint and base generation. A server location is not an Osnova semantic/type proof. Missing servers, stale offsets, unsupported methods, partial locations, request limits and cache contention remain explicit diagnostics while the structural index stays usable.
Default transport limits include 2-second requests, a 30-second session/refresh deadline, 128 requests and 8 pending requests per server, 1 MiB messages, 16 MiB traffic per direction, 16 servers, 256 queries/locations per result, 4,096 source files/64 MiB source snapshots, and a 16 MiB sidecar. Callers may lower transport limits, not raise hard maxima. Supplied executables are trusted processes, not OS-sandboxed. The client supplies isolated cache/config directories, rejects server-initiated requests, and stops only children it launched.
Policies and results persist separately under the workspace cache. Refresh retains still-valid complete evidence, retries failures, invalidates stale generations/source hashes and never starts a server merely because stored policy exists. No real language server is bundled, installed or auto-selected.
pnpm benchmark --samples 5 --output /existing/directory/candidate.json
pnpm benchmark --split evaluation --samples 5 --candidate-report /existing/directory/candidate.json
pnpm benchmark --manifest /path/to/corpus.json --workspace /path/to/checkout --output /existing/directory/result.jsonThe default benchmarks/core-v1.json is a small authored regression corpus, not representative evidence for large repositories. It separates development cases from explicitly selected evaluation cases. Evaluation labels are public and versioned, not a sealed test set. Freeze changes before evaluating; do not tune against evaluation scores. Corpus content and labels have a stable SHA-256 fingerprint, and each run also records input-snapshot, engine and harness fingerprints.
Evaluation commands require --candidate-report from a completed development run over the same corpus. Engine, harness, manifest, runtime environment and complete development case set must match; the input snapshot is checked before indexing or executing evaluation queries. The evaluation result carries a receipt identifying that candidate. Code, harness, labels or runtime changes require another development run. This is a local reproducibility guard, not a cryptographic signature, proof of task success, or a way to make public labels secret.
Additional source-pinned workloads are benchmarks/zod-v1.json (TypeScript), benchmarks/click-v1.json (Python), and benchmarks/pyright-v1.json (a TypeScript monorepo with Python test inputs). Their source repository and immutable revision are recorded in each manifest. They are small task sets over full checkouts, not comprehensive language coverage. Supply a clean checkout at that revision with --workspace; merely validating a manifest is not a measured benchmark result.
The runner launches a fresh process using tsx source execution, writes only into a disposable copy/cache and an explicitly requested result file, and runs no workload installation or test scripts. It never downloads a checkout. External corpus manifests require a full 40-character Git revision, a matching clean checkout with no untracked files, and source anchors independent of the extractor. Tracked files are copied independently of Osnova's scanner; symlink/submodule inputs are rejected. The supplied checkout is not edited. Output files are created exclusively, never overwritten.
A checkout manifest may declare source.exclude as exact relative files or directory prefixes, without glob syntax. Exclusions must match tracked input and cannot cover the edit file, source anchors, expected-result files, or the query target/scope. They are included in the manifest fingerprint and reported with the exact omitted paths as snapshotExclusions. The Zod workload excludes four enumerated agent-config/documentation symlinks; this does not relax the regular-file check for other inputs or follow symlinks.
Reports include raw expected/actual IDs, errors, source-validation failures, per-case latency and bounded text payloads. Metrics score structured query results, not what an agent can reconstruct from clipped text. Retrieval uses Recall@5 and reciprocal rank at 5; duplicate hits consume ranking positions. Caller precision/recall score distinct direct-call symbols by default, excluding reference/import edges, with traversal depth available per case. Text-search IDs use file:line:column, with one-based lines and zero-based columns. Correct empty sets score 1; unexpected results on empty ground truth score precision 0. Query errors remain in the aggregate denominator as zero; invalid source anchors invalidate that metric aggregate instead of disappearing from it.
Timing separates first build, unchanged hash refresh, and edited refresh including hash diff, incremental apply and cache write. Edit/revert setup and full-rebuild equivalence checks are outside the timed refresh samples. Percentiles use nearest rank; small sample counts provide only coarse smoke measurements. First build is process-cold for the parser, not a flushed filesystem-cache or process-startup measurement. Peak RSS includes the worker runtime and tsx, not just the graph. Serialized and on-disk artifact sizes are reported separately.
Each measured response additionally records its offline cl100k_base token count using the pinned development tokenizer, after query timing ends. This is an encoding-specific count of emitted text, not provider usage or total agent context. Agent task success, full-context counts, agent tool calls and packed-package size remain null until measured by their own trials. status: completed means measurement finished, not that retrieval was perfect; inspect the scores. Operational/query failures produce status: failed and command exit 2. This benchmark does not replace pnpm perf or the unit-test gates.
The initial development baseline records measured workload fingerprints, quality scores, refresh samples and limitations. It preserves misses rather than presenting successful execution as successful retrieval. Evaluation cases remain separate and were not used for that baseline.
The definition-ranking candidate records its frozen development/evaluation results and receipts. It improved retrieval on the small task sets, but preserves unresolved alias-caller misses and reports increased first-query costs. These results are not agent task-success claims.
The import-binding and scoped-declaration results record two separately frozen candidates, the nested-coverage regression found between them, and the corrected outcome. Exposed cases are labeled as regressions rather than reused as fresh validation.
The re-export results retain the frozen candidate receipt, positive and negative cases, development regressions and traversal limits. Self-host tests also verify callers through the public API barrel.
The receiver results retain the frozen receiver-hint evaluation, real-workload regressions and unsupported runtime behaviors. The measurements do not turn syntax-backed hints into type proofs.
The refresh optimization record contains apples-to-apples seven-sample before/after profiles, long-lived MCP reuse, stage timings, compression tradeoff and correctness limits. It records the measured repository/host method rather than claiming universal latency.
The parse profile splits a full build on the seven pinned checkouts into scan, grammar load, read and hash, tree-sitter parse, adapter walk, symbol assembly, resolve, serialize and save, timed on one thread in steady state with the wall clock recorded beside them, produced by scripts/parse-profile.ts. The WASM parse is 17 to 39 percent of attributed build time and the adapter walk 35 to 57 percent; on six of seven corpora the walk costs 1.9 to 2.7 times the parse. Native grammar bindings would shorten only the parse row and were not priced; the walk is the next lever.