Merge pull request #21 from Litenova-Solutions/feature/v3.1

V3.1: open-ended floor (S3 signal-sufficiency contract first)

Author: litenova

.github/workflows/ci.yml

@@ -28,7 +28,9 @@ jobs:
         run: |
           # Keep in sync with NuGetAuditSuppress entries in Directory.Build.props.
           $suppressedAdvisories = @(
-            'https://github.com/advisories/GHSA-hv8m-jj95-wg3x'
+            'https://github.com/advisories/GHSA-hv8m-jj95-wg3x',
+            'https://github.com/advisories/GHSA-vh6j-jc39-fggf',
+            'https://github.com/advisories/GHSA-h4j7-5rxr-p4wc'
           )
           $failed = $false
           Get-ChildItem -Path src -Recurse -Filter *.csproj | ForEach-Object {

AGENTS.md

@@ -2,6 +2,30 @@
 
 All notable changes to Fuse are documented here. The format is based on Keep a Changelog. Fuse 3.0 is a product overhaul; backward compatibility with 2.x output, commands, and the MCP tool surface is not a goal.
 
+## [3.1.0] - 2026-06-30
+
+Fuse 3.1 sharpens the .NET semantic engine on the modes where 3.0 was weakest: open-ended discovery, language breadth, and first-call latency. Dense retrieval is now on by default and fully offline, the open-ended path refuses and routes instead of guessing on a vague request, and more of the codebase's own vocabulary is searchable without a model. The numbers behind every claim are on the [benchmarks page](https://fuse.codes/docs/project/benchmarks).
+
+### Added
+
+- **Dense retrieval, on by default and offline.** A small local embedding model (all-MiniLM-L6-v2, about 23 MB) is fetched once and cached on the first index; every later run and all query-time work is offline, and the query is embedded as written, never paraphrased. It blends with the lexical and graph signals so a prose task finds a file by meaning. When the model is genuinely absent the path falls back to the deterministic lexical floor. Opt out with `FUSE_DENSE` set to a falsy value.
+- **Signal-sufficiency contract on the open-ended path.** `fuse_localize` now grades every request from the candidate score distribution into confident (return the tight set), partial (a small flagged set plus a navigation map), or insufficient (refuse and return only a navigation map and an explicit ask for a symbol, route, service, request, config section, or git base). On a no-signal title Fuse hands back a map instead of guessing. A `strict` option hard-requires an anchor; the default stays best-effort so a one-shot client is never stranded.
+- **Offline vocabulary bridges.** Identifier subword indexing (so the prose word `rounding` matches `ApplyRoundingMode`), Porter stemming, and a weighted comment field make the codebase's own vocabulary searchable without a model.
+- **Structural ranking signals.** A dependency-centrality prior and a git co-change prior (mined from a bounded git-history window at index time) nudge ambiguous candidates by where a file sits in the graph and which files it historically changes with. Both are capped so they tune rather than dominate.
+- **Iterative exploration tool.** `fuse_neighbors` returns the graph neighborhood of a file, the callers and implementers of a symbol, or the structurally central files of an area, ranked, bounded, and body-free.
+- **Multi-language breadth.** A provider seam drives the syntax tier; Python and JavaScript/TypeScript are supported at the syntax tier (token-efficient context and search) alongside C#. Each indexed file carries a `language` tag so retrieval can filter or blend by language. The deep typed graph remains .NET-only.
+- **Opt-in fast cold start.** In the `mcp serve` host, `FUSE_BG_UPGRADE=1` serves the syntax tier on the first read (no MSBuild wait) and upgrades to the full semantic graph in the background; the first answer drops from about 70 seconds to about 20 seconds on a mid-size repository.
+
+### Changed
+
+- **Open-ended localization is a graded contract, not a fixed candidate list.** Precision when the engine answers is up and false rejections on answerable queries are down; bare-title recall is no longer the headline for this path (the contract metrics are). With a git base, the routed mode remains change-impact review, which is where recall and precision are strongest.
+- **Persistent index schema bumped to version 14.** The index rebuilds on the first run after upgrade (it adds the subword, stem, and comment full-text fields and the file language tag). No action is needed; the rebuild is automatic.
+- **Benchmark corpus rebuilt and peer comparison expanded.** The corpus now uses repositories that restore and index in semantic or partial mode on the .NET 10 SDK, and the peer comparison runs Fuse against CodeGraph, coa-codesearch, and Serena head-to-head. The benchmarks page and the docs are rewritten as current-state snapshots.
+
+### Fixed
+
+- **Directory walk no longer escapes the collection root through a symlinked or junctioned directory.** A file reached by descending through a reparse-point directory that points outside the root is now excluded, matching the existing handling for file symlinks.
+
 ## [3.0.0] - 2026-06-26
 
 Fuse 3.0 turns Fuse from a token-reduction context optimizer into a Roslyn-backed .NET semantic context engine for AI agents. It maintains a warm, persistent semantic index of a workspace and serves precise, provenance-backed context from it: which implementation is injected, which endpoint handles a route, which handler processes a request, which options type binds a config section, and what a git diff semantically impacts. Token reduction is now a rendering and transport feature, not the product.

CHANGELOG.md

@@ -24,10 +24,12 @@
   <ItemGroup>
     <!-- MessagePack arrives only as a transitive of StreamJsonRpc (the UI host transport) and flows into every
          project that references Fuse.Cli, including the test projects. It is never exercised: the host uses the
-         System.Text.Json formatter, not the MessagePack formatter, so the MessagePack deserialization advisory
-         (GHSA-hv8m-jj95-wg3x) is unreachable. Suppressed repo-wide with that documented intent rather than
-         pinning a 3.x MessagePack that StreamJsonRpc 2.x does not accept. -->
+         System.Text.Json formatter, not the MessagePack formatter, so the MessagePack deserialization advisories
+         are unreachable. Suppressed repo-wide with that documented intent rather than pinning a 3.x MessagePack
+         that StreamJsonRpc 2.x does not accept. GHSA-hv8m-jj95-wg3x is the moderate untrusted-data advisory;
+         GHSA-vh6j-jc39-fggf is the high-severity advisory on the same package and code path. -->
     <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-hv8m-jj95-wg3x" />
+    <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-vh6j-jc39-fggf" />
     <!-- Microsoft.Build.Tasks.Core 17.7.2 arrives only as a reference-only transitive of
          Microsoft.CodeAnalysis.Workspaces.MSBuild. At runtime the real MSBuild assemblies are
          resolved from the installed SDK via MSBuildLocator.RegisterDefaults(), not this restored

Directory.Build.props

@@ -0,0 +1,74 @@
+# Launch post and demo script
+
+This file is the launch material drawn from the [messaging source of truth](site/content/docs/project/messaging.mdx). Every number is quoted from `tests/benchmarks/results` and linked to the [benchmarks page](https://fuse.codes/docs/project/benchmarks); no head-to-head ranking is claimed beyond what the peer harness measures. The 30-to-60-second screen-capture demo is recorded from the script below (see "Status" at the end for what remains a manual step).
+
+## Launch blog post (draft)
+
+### AI coding assistants get lost in .NET codebases, and it costs you tokens
+
+Watch an AI assistant start a task in a real .NET solution. Before it changes a line, it explores: it lists directories, greps for a name, and opens file after file trying to learn which ones matter. On a solution with hundreds of C# files, most of the context window goes to the hunt, not the change. And there is a class of question it cannot answer by grepping at all: which class does the container actually inject for this interface? Which handler runs this request? Which action does this route hit? Those answers live in the wiring, not in the file names, so the assistant guesses, and a wrong guess sends it opening more files.
+
+That is the problem Fuse attacks.
+
+Fuse is a Model Context Protocol server for .NET. It reads your code with Roslyn and builds a typed graph of how the code is wired, then serves your assistant the files a task needs, scoped and reduced, in one call. The assistant answers from the real graph instead of guessing, spends fewer tokens, and stops paying for the explore loop.
+
+What that looks like in practice, on the eShopOnWeb sample application:
+
+- Ask "what implements `IBasketService`, and what would a change to it touch?" Without Fuse, the assistant greps `IBasketService`, gets a page of hits, and opens files to work out which is the real implementation. With Fuse, `fuse_resolve service="IBasketService"` returns `BasketService` directly, tagged with the `di_resolves_to` edge and the registration that proves it.
+- Ask it to review a branch. `fuse_review changedSince="main"` returns the changed files plus their semantic blast radius (the interface a changed type implements, its consumers) with provenance for each file, in about 958 tokens, keeping 100 percent of the changed files.
+
+The numbers, measured over a commit-pinned corpus (Scrutor, Ardalis.Specification, NodaTime, and eShopOnWeb), counted with `o200k_base`, and reproduced with `fuse eval`:
+
+- The extracted wiring graph matches the hand-built ground truth exactly on the wiring fixture: 22 of 22 edges, recall and precision 1.0.
+- `fuse review` over 53 real merged pull requests keeps 100 percent of the changed files at 79.8 percent precision in a median 958 returned tokens; a grep baseline reaches 53 percent recall at 14 percent precision.
+- Driving Claude (sonnet-4-6) over 12 pull requests, the Fuse MCP arm edged out bare filesystem tools on file recall (30 versus 26 percent) at comparable token cost, on a small, model-dependent sample.
+
+And the honest part, because honesty is the point of a tool you trust with your codebase: the weakest mode is open-ended localization from a bare task title with no git base, where Fuse recalls about 15 percent of the changed files. Rather than return a low-precision guess on a title that names no code, Fuse refuses and hands back a navigation map asking for a symbol, a route, or a git base. Every number above, including that one, is on the [benchmarks page](https://fuse.codes/docs/project/benchmarks) with the reproduction command, and the peer comparison there is the only place a head-to-head is stated, because that is the only place the harness backs it.
+
+Install it, connect it to your agent, and give your assistant a map of your code:
+
+```bash
+dotnet tool install -g Fuse
+fuse mcp install --rules
+```
+
+It works with Claude Code, Cursor, and GitHub Copilot. The deepest support is on .NET; other languages are covered at the syntax tier today.
+
+### Channels
+
+- The .NET communities: r/dotnet, the .NET Discord, and a dev.to / blog cross-post.
+- The MCP ecosystem: the MCP Registry (the manifest is in `mcp-registry/server.json`) and the awesome-mcp-servers lists.
+- A Show HN with the honest-benchmarks angle (lead with the problem and the reproducible numbers, including the weak mode, not a ranking).
+
+## Demo script (eShopOnWeb, reproducible)
+
+A 30-to-60-second screen capture follows this script. It is a real session on a recognizable .NET application already in the corpus, showing the same two questions answered with and without Fuse. The point is correct-and-cheap with Fuse versus lost-without-it; it does not assert a head-to-head win over another tool.
+
+Setup (once):
+
+```bash
+git clone https://github.com/dotnet-architecture/eShopOnWeb
+cd eShopOnWeb
+dotnet tool install -g Fuse
+fuse index .
+```
+
+Scene 1, without Fuse (bare tools): ask the agent "what implements IBasketService and what does a change to it touch?" Show it grepping, getting many hits, and opening several files to guess the implementation and consumers.
+
+Scene 2, with Fuse: ask the same question. Show:
+
+```bash
+fuse resolve --service IBasketService
+# -> BasketService (src/ApplicationCore/Services/BasketService.cs), edge di_resolves_to
+
+fuse review --changed-since main
+# -> changed files + support files (the IBasketService interface, its consumers),
+#    100% of changed files kept, ~958 tokens median, with provenance
+```
+
+End on the contrast: one scoped, provenance-backed answer instead of a file-opening hunt.
+
+## Status
+
+- Written and sourced: the launch post, the channel list, and the reproducible demo script (above).
+- Remaining manual steps (cannot be produced from the build environment): record the screen capture from the demo script, publish the post to the chosen channels, and link the published asset from the landing page hero and the README. Until the recording exists, the landing page and README link the sourced benchmarks rather than a video, to avoid linking an asset that is not yet published.