Make string demo handlers opt in

[Eli Pinkerton (wallstop)]

Why

Every MessageAwareComponent registered three demo string handlers by default. Ordinary components retained registrations they did not request.

The setup guide implied that MessagingComponent was required. The diagnostics tour did not expose common failure and visibility states, and CI did not consume the package artifacts it exported.

What changed

• String demo handlers now require RegisterForStringMessages.
• The 3.x upgrade tool preserves inherited string handlers when it can prove a safe edit.
• Existing opt-in properties stay unchanged. Partial types receive a manual-review warning.
• DXMSG006 now warns about missed inherited registrations.
• Setup and migration guides explain the new behavior.
• Benchmark docs link to immutable evidence with verified hashes.
• The diagnostics tour reproduces disabled, missing-token, destroyed, and stale states.
• The tour emits through a separate bus and standalone token.
• Its status shows isolated registration, log, callback, and trace evidence.
• A default-off manual matrix installs the exact Git SHA, generated UPM tarball, and classic package in clean projects, imports all four samples, and runs the existing eight sample-flow cases.

How we know

• Existing tests prove the isolated action does not register or emit on the global bus.
• Release clears the isolated registration and its retained log.
• All 1,321 script cases, validate:all, formatting, spelling, package, analyzer, and workflow-policy checks pass locally.
• The final manual matrix passed Git, generated-tarball, and classic installation on all four Unity versions. All 12 evidence records imported four samples and passed 8/8 tests with no failures or skips.
• All eight ordinary pull-request workflows and the manual four-version consumer matrix pass on exact head cb8e6406.
• No retry, timeout, test method, test category, job, schedule, or recurring CI scope was added.
• The manual lane replaces ordinary modes inside the existing 90-minute step.

Related work

Refs #502.
Refs #506.
Refs #507.
Refs #508.
Closes #573.

Issue #502 remains open. Issue #573 is complete and closed with its GREEN/keep evidence recorded.

---

Note

High Risk
Breaking default behavior for every MessageAwareComponent subclass that relied on implicit string demos without an explicit opt-in; CI and export paths add substantial new validation surface.

Overview
Breaking (4.0): MessageAwareComponent no longer registers built-in string demo handlers unless subclasses override RegisterForStringMessages => true. Docs, README, and DXMSG006 messaging now describe inherited/parent registrations instead of “default string handlers.”

The Upgrade 3.x Fast Handlers to 4.0 editor tool still converts ref → in and, when it updates inherited string-handler overrides, can insert RegisterForStringMessages => true (with manual-review paths for partial types and existing opt-outs).

The Diagnostics Tooling Exerciser guided tour adds steps for disabled receivers, released tokens, destroyed components, and emissions on a separate MessageBus/standalone token so global Message Monitor/Flow Graph boundaries are explicit.

CI: workflow_dispatch gains optional consumer_install_validation (mutually exclusive with shipping_fidelity). That path runs export-unitypackage.ps1 with -VerifyConsumerInstalls, installing the exact Git SHA, UPM tarball, and classic .unitypackage in clean projects, importing all four samples, and running the eight existing sample contract tests. Builtin module manifest drops com.unity.modules.vr for matrix compatibility.

Tests, snippet-compilation regex, and perf-evidence runbook entries are updated to match.

^{Reviewed by Cursor Bugbot for commit cb8e640.}

[github-actions]

Performance Numbers

Measured commit: cb8e640
Trusted reporting code (PR base): db12a9d
Measured historical baseline: 1590dd3
Workflow run: 34592289541 attempt 1

Benchmark methodology and execution profile are unchanged; the historical Standalone comparison is diagnostic regression smoke.

Historical Standalone delta

Delta direction: + is better; - is worse.

Scenario	Baseline	Current	Delta
Empty Bus Dispatch	51.61 M emits/sec	51.07 M emits/sec	-1.05%
Untargeted Flood (One Handler)	46.62 M emits/sec	46.00 M emits/sec	-1.34%
Untargeted Flood (One Direct Handler)	48.46 M emits/sec	47.41 M emits/sec	-2.17%
Untargeted Flood (Two Handlers, One Priority)	43.37 M emits/sec	44.30 M emits/sec	+2.15%
Untargeted Flood (Three Handlers, One Priority)	40.77 M emits/sec	40.95 M emits/sec	+0.43%
Untargeted Flood (Four Handlers, One Priority)	38.49 M emits/sec	36.33 M emits/sec	-5.60%
Untargeted Flood (Four Handlers, Four Priorities)	39.19 M emits/sec	38.19 M emits/sec	-2.56%
Untargeted Flood (Sixteen Handlers, One Priority)	22.25 M emits/sec	22.42 M emits/sec	+0.77%
Untargeted Flood (One Inactive Handler)	48.47 M emits/sec	49.47 M emits/sec	+2.07%
Untargeted First Dispatch (Cold, Distinct Types)	0.200 ms	0.184 ms	+8.00%
Targeted Flood (No Matching Target)	18.24 M emits/sec	17.69 M emits/sec	-3.03%
Targeted Flood (One Listener)	15.42 M emits/sec	15.05 M emits/sec	-2.44%
Targeted Flood (Sixteen Listeners)	11.14 M emits/sec	11.06 M emits/sec	-0.73%
Targeted First Dispatch (Cold, Distinct Types)	0.202 ms	0.189 ms	+6.44%
Broadcast Flood (One Handler)	32.28 M emits/sec	31.94 M emits/sec	-1.07%
Broadcast First Dispatch (Cold, Distinct Types)	0.233 ms	0.187 ms	+19.74%
Targeted Post Route (Stable)	27.83 M emits/sec	26.15 M emits/sec	-6.01%
Targeted Post Route (Rewritten, Empty Final Route)	23.08 M emits/sec	22.89 M emits/sec	-0.81%
Targeted Post Route (Rewritten, Populated Final Route)	17.49 M emits/sec	16.50 M emits/sec	-5.70%
Broadcast Post Route (Stable)	28.16 M emits/sec	27.79 M emits/sec	-1.30%
Broadcast Post Route (Rewritten, Empty Final Route)	25.99 M emits/sec	24.47 M emits/sec	-5.87%
Broadcast Post Route (Rewritten, Populated Final Route)	18.31 M emits/sec	17.50 M emits/sec	-4.45%
Interceptor Heavy (Four Interceptors)	35.14 M emits/sec	33.98 M emits/sec	-3.30%
Post-Processing Heavy (Four Post-Processors)	28.89 M emits/sec	29.02 M emits/sec	+0.46%
Message Bus Construction (1000)	17.229 ms	16.507 ms	+4.19%
Registration Token Construction (1000, Prebuilt Handler + Bus)	0.049 ms	0.046 ms	+6.12%
Registration Flood (1000 Types, Cold Bus)	489.839 ms	472.543 ms	+3.53%
Registration Flood (1000 Types, Warm JIT)	3.236 ms	3.414 ms	-5.50%
Untargeted Registration (Marginal, 1000 Same-Type)	0.437 ms	0.432 ms	+1.14%
Targeted Registration (Marginal, 1000 Same-Type)	0.474 ms	0.477 ms	-0.63%
Broadcast Registration (Marginal, 1000 Same-Type)	0.483 ms	0.480 ms	+0.62%
Deregistration Flood (1000 Types, Cold)	2.123 ms	2.250 ms	-5.98%
Deregistration Flood (1000 Types, Warm JIT)	1.252 ms	1.549 ms	-23.72%
Registration Attribution (Direct Bus, 131072)	30.918 ms	30.123 ms	+2.57%
Registration Attribution (Direct Handler, 131072)	67.567 ms	65.194 ms	+3.51%
Registration Attribution (Token Stage, 131072)	11.147 ms	12.064 ms	-8.23%
Registration Attribution (Token Active, 131072)	95.285 ms	90.975 ms	+4.52%
Deregistration Attribution (Direct Bus, 131072)	7.371 ms	7.129 ms	+3.28%
Deregistration Attribution (Direct Handler, 131072)	30.224 ms	27.890 ms	+7.72%
Deregistration Attribution (Token Remove, 131072)	36.252 ms	31.405 ms	+13.37%
Deregistration Attribution (Token Disable, 131072)	32.659 ms	32.220 ms	+1.34%
Global -> 1 subscriber	46.16 M emits/sec	46.48 M emits/sec	+0.68%
Global -> 16 subscribers	20.82 M emits/sec	21.07 M emits/sec	+1.21%
Keyed/targeted -> 1 of many	12.49 M emits/sec	15.79 M emits/sec	+26.40%
Priority-ordered dispatch	37.51 M emits/sec	37.29 M emits/sec	-0.61%
Filtered/intercepted dispatch	35.20 M emits/sec	36.37 M emits/sec	+3.32%
Post-processing dispatch	29.53 M emits/sec	30.85 M emits/sec	+4.45%
Intercepted + post-processed dispatch	27.05 M emits/sec	28.08 M emits/sec	+3.77%
Subscribe/unsubscribe churn	1.37 M emits/sec	1.40 M emits/sec	+2.06%
Struct message (no boxing)	43.40 M emits/sec	43.43 M emits/sec	+0.07%

Current TargetMap evidence

These raw rows are current-run diagnostics. Use fresh bracketed controls before accepting a micro-optimization.

[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Churn keyCount=16 operation=Churn totalOperations=2120000 operationsPerSecond=422714.534 wallClockMs=5015.205 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=2140000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Hit keyCount=16 operation=Hit totalOperations=77790000 operationsPerSecond=15557719.650 wallClockMs=5000.090 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=77810000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Miss keyCount=16 operation=Miss totalOperations=79430000 operationsPerSecond=15884903.624 wallClockMs=5000.345 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Churn keyCount=1 operation=Churn totalOperations=2150000 operationsPerSecond=428221.997 wallClockMs=5020.760 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=2170000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Hit keyCount=1 operation=Hit totalOperations=76340000 operationsPerSecond=15267454.036 wallClockMs=5000.179 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=76360000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Miss keyCount=1 operation=Miss totalOperations=81640000 operationsPerSecond=16326585.791 wallClockMs=5000.433 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Churn keyCount=256 operation=Churn totalOperations=2040000 operationsPerSecond=406755.531 wallClockMs=5015.298 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=2060000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Hit keyCount=256 operation=Hit totalOperations=68440000 operationsPerSecond=13686234.749 wallClockMs=5000.645 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=68460000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Miss keyCount=256 operation=Miss totalOperations=77350000 operationsPerSecond=15469625.326 wallClockMs=5000.121 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Churn keyCount=4096 operation=Churn totalOperations=1840000 operationsPerSecond=367070.072 wallClockMs=5012.667 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=1860000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Hit keyCount=4096 operation=Hit totalOperations=62500000 operationsPerSecond=12499845.502 wallClockMs=5000.062 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=62520000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Miss keyCount=4096 operation=Miss totalOperations=77130000 operationsPerSecond=15425424.323 wallClockMs=5000.187 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Churn keyCount=4 operation=Churn totalOperations=2120000 operationsPerSecond=423439.527 wallClockMs=5006.618 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=2140000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Hit keyCount=4 operation=Hit totalOperations=75780000 operationsPerSecond=15153937.549 wallClockMs=5000.681 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=75800000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Miss keyCount=4 operation=Miss totalOperations=81030000 operationsPerSecond=16204657.606 wallClockMs=5000.414 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=0
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=1 wallClockMs=0.000107 operationsPerSecond=9310986.965 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=4
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=16 wallClockMs=0.000648 operationsPerSecond=1542168.675 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=32
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=256 wallClockMs=0.007775 operationsPerSecond=128617.363 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=512
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=4 wallClockMs=0.000220 operationsPerSecond=4545454.545 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=8
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=4096 wallClockMs=0.125000 operationsPerSecond=8000.000 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=8192

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 814bb7f. Configure here.}