[richlander]

Host-issued exact-match presentation pilot

dotnet-inspect builds robust, capable inspection features that provide
foundational capabilities or compelling experiences and are conventionally
sound, delightfully new or unique, or both.

This final prototype slice tests a narrow consequence of byte-native names:
when a host-issued user value exactly matches a stored Name, presentation can
reuse the original host text instead of decoding and containing the matched
artifact bytes.

Stack

• Slice 1/3: Add Symbol Key range representation pilot #10034 — corrected Symbol Key range harness and parity gates
• Slice 2/3: Record Symbol Key range pilot evidence #10035 — scoped reader tuning and accepted representation evidence
• Slice 3/3: this PR — host-issued exact-match presentation pilot

Both parent slices are merged. This PR targets main and tracks #9918.

Design basis

Normative owner:
docs/design/inert-bytes.md#UTF-8-query-operations
owns byte-exact closed comparison without decoding or promoting stored bytes.

The pilot adds an explicit provenance shape:

• UserSearchValue is constructed at the host boundary and retains the
  original text plus one UTF-8 encoding.
• Utf8RangeReader.TryMatchUserText performs the same byte-exact comparison.
• Success returns UserTextMatch, whose presentation is the original host
  text; it does not expose or strengthen the opaque artifact range.

The type makes construction sites easy to audit. It is not a capability barrier
against trusted in-process code, and it does not admit artifact-derived,
normalized, fuzzy, prefix, case-insensitive, or arbitrary UTF-8 promotion.

Measurement

present --user-text <text> compares two paths over the same
population-backed store:

Scenario	Baseline	Candidate
ScanAndPresent	Scan by exact bytes, then decode and contain every match	Scan by the same exact bytes, then reuse matched host text
MatchedNamePresentation	Repeatedly decode and contain one already-matched Name	Repeatedly consume the proven UserTextMatch

The second scenario isolates the post-match work that a large scan can hide.
The baseline uses current UTF-16 InertString as a stand-in for the planned
InertUtf8String; product adoption must compare against that real currency
once it exists.

Exact-head NativeAOT evidence

Measured code commit 8b61ed18e28103843d238eeaec42cd71c94bffcf
ran as linux-x64 NativeAOT on dotnet-inspect-perf under one perf-guard
lease. The host was 99.75% idle. Thirty rotated rounds used .ctor over at
least 50,000 keys per asset. Binary SHA-256:
885ee6954f968bdfd70e044b46f1b636e024968546fec57b4ef239909fefad5b.

Ratios are ReuseHostText / DecodeAndContain:

Asset	Keys	Matches	Scan + present	Matched presentation	Baseline scan allocation	Candidate allocation
CoreLib	62,986	2,553	0.927x, win	0.124x, win	81,696 B	0 B
System.Text.Json	53,662	2,422	0.917x, win	0.124x, win	77,504 B	0 B
Configuration	50,290	2,889	0.881x, inconclusive	0.124x, win	92,448 B	0 B

Matched-presentation control intervals were 0.079x-0.159x,
0.088x-0.161x, and 0.106x-0.142x. Full scan-and-presentation intervals were
0.883x-0.961x, 0.884x-0.957x, and 0.727x-1.026x. Candidate timed allocation was
zero in every cell; the isolated baseline allocated 32 bytes per operation.
Every baseline and candidate cell produced identical output.

Head c3dfb224511a0ca06b69b0da81bd11d785394890 adds only the evidence record
above measured commit 8b61ed18e; no compiled source changed after the exact
run.

Decision boundary

The shortcut has a clear post-match benefit and can materially help when one
query presents many exact matches. It does not establish a general scan-speed
win. This evidence supports carrying the explicit host-input type into product
design; it does not authorize promoting matched opaque ranges into trusted text
or bypassing InertUtf8String for non-user provenance.

Validation

dotnet build tools/SymbolKeyRangePilot/SymbolKeyRangePilot.csproj -c Release
dotnet run --project tools/SymbolKeyRangePilot -c Release -- check <assets>
dotnet run --project tools/SymbolKeyRangePilot -c Release -- \
  measure --rounds 2 --target-keys 1000 <asset>
dotnet run --project tools/SymbolKeyRangePilot -c Release -- \
  present --user-text .ctor --rounds 3 --target-keys 5000 <assets>
npx markdownlint-cli tools/SymbolKeyRangePilot/README.md

[richlander]

Round 1 carry-forward for candidate head c3dfb224511a0ca06b69b0da81bd11d785394890.

Before reviewer dispatch, main advanced from the branch base f473e8002981eda4f2d39893dd99a54298c54218 to 3bc74c2cf342d3d5be148df9cbe934abf1a7954d through #10033, #10009, #10007, #10023, #10006, and #10025. The landed range touches metadata, query, presentation, CLI, Web, and design surfaces; it does not touch tools/SymbolKeyRangePilot/**, src/InertText/**, the pilot build configuration, or any measured input. The local merge-tree probe is clean.

Classification: no interaction. The candidate head remains unchanged and its exact-head NativeAOT evidence remains applicable. Auto-merge is unarmed. Review waits for current-head ci-required.

[richlander]

Closing this prototype because its comparison answers the wrong performance question.

The candidate path reused host text, but the baseline decoded every matching UTF-8 Name into a new InertString. The reported allocation difference was therefore exactly 32 bytes of UTF-16 materialization per displayed match; retained memory was not measured, and the repeated scenario amplified one match across roughly 50,000 operations. This does not compare the intended byte-native OpaqueByteRange / InertUtf8String path.

No review was dispatched and auto-merge was never armed. The replacement plan is two independently reviewable slices: first adopt OpaqueByteRange and InertUtf8String in one focused product search/presentation path; then add the host-issued exact-match optimization and compare it directly against that merged baseline. The type command is being evaluated as the first single-result adoption scenario.