feature/bufix: AOT-Compatible Protobuf Serialization #343

DISCLOSURE: LLM-GENERATED TEXT

Active WProto roadmap — 2026-10-18

Objective: preserve the architecture and establish authoritative compatibility and measurement evidence before retaining optimizations. Target at least 2× protobuf-net v3 throughput for reads and writes separately on a frozen representative floor/latest Mono corpus. This target remains unproved.

Locked decisions

• Freeze each versioned contract's tags, defaults, packing, ordering, root/surrogate encodings and historical hash behavior. Distinguish identical bytes, readable alternatives and named oracle defects. Retain the approved v3 map policy and documented v2 exceptions.
• Keep ISourceGenerator, Unity 2021.3's compiler API floor, checked access, bounded recursion, static AOT registration and the hybrid facade.
• Compare baseline/candidate on the same IL2CPP or WebGL backend; do not form ratios across runtimes. Third-party AOT comparisons require matching supported schemas.
• Prioritize consumer compatibility, then low-allocation APIs, then broader models. Retire bundled runtime DLLs through a separately qualified major release. Full gRPC, schema import and unrelated JSON expansion remain separate; JSON/AOT migration regressions remain covered.

Work sequence

1. Complete the versioned contract/API/capability ledger: executable witnesses for every advertised capability, named regressions for exceptions, retained goldens and required reader directions.
2. Complete #633: establish trustworthy correctness and performance evidence gates #636's scientific baseline: seven equally weighted families and retained consumer shapes; small/typical/large and empty/boundary values; direct/public, array/reusable and appropriate buffer/stream APIs; identical read bytes, cold/warm use and default/finite limits. Preserve 32 calibrated observations per arm, controls, raw samples and immutable baselines.
3. Extend independent semantic assertions and cumulative element/copy/work limits under #633: fuzz and benchmark Wallstop Proto / JSON end to end #647. Preserve failure latching and the distinct dispatch/data-error contracts of public Try APIs. Prove seeded host-only tooling before adoption under #633: evaluate host-only formal, mutation, schedule, fuzz, and Burst experiments #649.
4. Test one measured hypothesis per change: enum casts; packed-count reuse; repeated bulk reads; varint sizing/writing; tag/generic resolution; text/nested planning. Require at least 5% improvement in the preregistered end-to-end metric with favorable confidence bounds and no undeclared allocation/retention regression. Enforce size budget max(1%, 3 × baseline MAD).
5. Expand supported ProtoBuf/DataContract metadata and migrations from actual runtime-model tags; remaining generic/immutable/interface/nullable shapes and formats; bounded raw unknown retention; caller spans, public limits, segmented IO and eligible reusable reads; then bounded graph/reference feasibility with generated factories and explicit type allowlists. #633: fuzz and benchmark Wallstop Proto / JSON end to end #647 retains the detailed feature acceptance.

Published work, limited scope

The branch feat/wproto-compatibility-evidence retains the initial metadata ledger, cumulative tag limit, frozen synthetic warm corpus, parent-aware duplicate validation, public source API freeze and owned formatter failure fix.

The capability evidence foundation, diagnostic assertion follow-up, and nested-write failure fix recorded 167 claims, 518 source selectors, 88 fixture bindings and 19 named gaps (10 open / nine resolved). G019 is resolved for the main guide’s finite 37-code inventory: 40 reviewed identifier/severity assertion bindings and 78 exact cases per host lane, including separate WPROTO041 player/Editor/symbol controls. Those full Release suites passed 1,740 v3 / 1,709 v2, zero failures/skips; strict invocation receipts accept 46 complete selected fixtures in each host lane. Source-declaration checks remain syntax-only; reviewed assertion meaning is not inferred by the verifier. CoreCLR receipts do not qualify whole capabilities or Unity processes. Exact identities, compiled negative controls, 127 verifier controls and remaining gaps are recorded under #647. These commits are pushed but unmerged; no full PR matrix has run.

The nested-write follow-up contains exceptions from a contract-violating custom formatter at the existing TryWriteMessage boundary: it preserves the exception and partial bytes, unwinds its frame and refuses continuation. Six compiled failure controls turn green while two normal-write controls stay green. Unity 6000.4.6f1 Editor Mono at that revision reported 2,665 serialization passes, zero failed/skipped assertions and four existing inconclusive allocation controls; all 33 formatter cases pass. This is scoped Editor evidence and does not resolve retained native-process failures.

Earlier Unity 6000.4.6f1 Editor Mono evidence at 1053338b records 2,657 serialization passes and four existing inconclusive allocation probes. It is historical scoped correctness evidence, not the requested current floor/latest player acceptance.

Earlier merge-copy resource slice: the shared message-merge copy limit adds an opt-in cumulative allowance while preserving existing constructors and unlimited defaults. The ledger now has 168 claims, 535 selectors, 88 fixtures and 2,380 API records, retaining every prior API record; 19 named gaps remain (10 open). At that revision, full Release suites pass 1,796 v3 / 1,765 v2, zero failures/skips, with 46 complete selected fixtures accepted per host lane. Unity 6000.4.6f1 Editor Mono reports 2,705 serialization passes, zero failures/skips and four existing inconclusive allocation controls; all 169 read-limit cases pass. Native generated-route coverage remains partial. Three retained CoreCLR campaigns fail calibration/stability controls and expose an adverse default-read signal; the optional inlining experiment was rejected. #636 records raw identities and remaining measurement work; #647 records exact source/build receipts. The branch is pushed but unmerged, no PR is open, and performance/player/whole-capability acceptance remains open.

Current publication (2026-10-19): 45fa9e55 adds #1041’s build-only debugger route after #1040’s collection cap ated836fd. Pushed/unmerged; no PR. Existing pins, bounded output, private dumps and distinct controller/target exits are reused; default builds and registry policy remain. Fresh hosts2,002/1,971 retain actualed836fd and the same5,901 C# inputs; all seven tooling files are outside that census. Native controls229 Linux/321 Windows, actual normal/AV programs and four removed-guard controls pass their intended outcomes. Diagnostic39216476665 is active, explicitly stopping before player/timing execution. Earliered836fd correctness39208037008 passes assertions/cleanup but retains11 rawC0000005 exits; readback39208971293 recovers no event/dump. Native causes, remaining resource/semantics, representative2×, backends, rollout and retirement remain open.

Release gates still open

Require the lower 95% bound of the equally weighted family geometric mean to reach 2× separately for reads/writes on floor/latest Mono; every workload must remain within the 5% non-inferiority margin. Unstable measurements are inconclusive.

Complete Unity 2021.3/2022.3/6000.5/6000.6 configurations; non-development Mono and high-stripping IL2CPP players; actual WebGL browser execution with negative controls; startup, allocations, retention and code-size qualification; rebuilt/verified shipped generators; explanation of retained native-process failures; and complete Shiro, DoxReloaded and IshoBoy upgrade/write/rollback-read acceptance using copies of preserved saves. Passing XML or a retry does not explain a process fault.

Consumer availability is no longer a general blocker. DoxReloaded retains eleven save-derived protobuf payloads; IshoBoy retained-save checks exercise JSON/SQLite. Shiro evidence covers source compilation and constructed shapes, not retained gameplay saves. Full deployment and dependency/API retirement remain open.

#647 owns correctness/performance, #636 measurement and #649 bounded host tooling. Keep this umbrella open until its full acceptance is proved.

Historical evidence

The records below retain their original revisions and qualifications; older “current head,” capability and availability summaries are not current acceptance.

Session closeout — 2026-10-18: PR #1025 was merged by wallstop as 5b0252856a814f9bb6d87ecb4a37287da52125e2. The reviewed head is 2c9784a63ae1b6286678d8d2adf751ed3920313d. It adds checked short-varint reads and prefix continuation, preserves malformed-input and packed-budget behavior, replaces authored validation-rule JSON copies, and records Standalone Editor build exits. Both Release oracle suites pass (1,405 v3 / 1,374 v2), plus the targeted native fixtures. Scoped Editor samples improve, but the broad 2× read target is not proven.

Final-head CI: All 29 current-head checks are terminal: 23 successful and six expected conditional formatting skips. All eight PR workflows pass, including the single regular Unity 6 repeat and final aggregates. The owner review request is addressed and its thread resolved; all feedback surfaces were checked. The repeat records 6,168 EditMode, 19,165 PlayMode, 16,639 Standalone and 82 WProto-only passing cases, zero failed assertions, and confirmed healthy cleanup. The original scene allocator-warning failure remains unresolved on #393; a successful repeat does not fix it.

Native evidence remains open: The current 2021 report, current 2022 report, and verified build-receipt comparison retain the exact scope. Both first-attempt 6000.6 Editor builds record 0xC0000005. The repeat's verified Standalone artifact 12121704400 (SHA256 5f81c2d274e0265d20b87057570528b75b1deb5246723bed5296676a07279a56) also records that Editor build exit, with no watchdog kill and zero native report headers, before the successful player run. No assertion or artifact acceptance policy was weakened. Keep this issue open for its broader performance, native-cause, compatibility, retirement and rollout acceptance below.

Earlier session records below are historical and apply to the revisions named in them.

Session closeout — 2026-10-17: PR #1020 merged as 480a360374c4b54be247b38f91aa39f195098bcc and PR #1022 merged as e16099437044f8d534914b85391610e1d26b1028. GitHub native stack #1021 landed both atomically with squash and no rule bypass. Reviewed heads 7508f55a and 27743eeb passed all 29 / 28 checks respectively (23 / 22 successful, six expected skips each), with resolved review threads and complete feedback checks. Fetched main is e1609943; its tree exactly matches the tested upper head (8c2fe44ff612428412a29ea7157a03f3adfe8d78). Both worktrees are clean.

Scoped correctness: The generated WebGL player passes 23 normal cases plus both negative controls with zero browser errors. This remains scoped correctness evidence. Passing tests and healthy cleanup do not explain the retained native reports.

CI qualifications: All acquired PR jobs, including failed and cancelled attempts, confirm healthy license cleanup and lock release. The allocator-warning failures and subsequent successful single-job retries are retained in #393; successful retries do not fix that defect. The watchdog scheduling cancellation is retained in #1023. Both follow-ups stay open. Passing Unity 2021/2022 jobs still contain UNKNOWN reports, including the naming-validator scan and NUnit discovery. Native causation and safety acceptance remain open.

Native investigation: The approved one-time comparison run 39002999733, pinned to 91f2aca7, failed at the initial writable registry-key open before any lease, comparison phase or flag write. Its independent restore failed because no receipt existed. All six acquired jobs confirmed healthy cleanup. Verified artifact and outcome. No permissions were granted and the comparison was not repeated; no before/disabled/restored result exists. The resulting recovery gap is fixed in merged #1020: prepare through read-only access before requesting a write handle, and verify unchanged-state recovery without write rights. Local controls pass 168 Windows / 76 Linux; CI passes 167 Windows controls (the local absent Unity.exe setting adds one observation assertion).

Scoped size evidence: The safe / retained / safe WebGL enum comparison passes all three 23-case browser matrices and negative controls. The safe Wasm repeat is stable at +47,978 bytes (0.0716%); Data varies by one byte, so no total shipping-size delta is claimed. This does not complete broader performance or code-size acceptance.

Still open: Full protobuf dependency/API retirement and coordinated rollout, complete backend/type acceptance, qualified paired performance/allocation and code-size evidence, full Shiro deployment and retained-save acceptance, and native-fault and prior scene-assertion explanations. Copied IshoBoy/DoxReloaded retained-data IL2CPP checks and Shiro source compilation retain their recorded scope and qualifications. Earlier records below preserve their original revisions and acceptance limits.

Earlier issue records and acceptance criteria follow; their “current/final head” statements refer to the revisions named there.

2026-10-16 current update: The real-consumer availability blocker is cleared. Copied IshoBoy and DoxReloaded snapshots pass scoped retained-data checks in non-development Release/high-stripping Windows IL2CPP players; Shiro's source-only snapshot compiles all 1,451 scripts. Required source qualifications and legacy-field handling are recorded in the current evidence. A fresh native report remains unexplained and the final-head Unity matrix is still running. Full release, performance and deployment acceptance remains open.

Earlier records below retain their original heads and validation scope.

Current-head CI evidence

All 31 checks on PR #1015, head 3fdddcf74e82f2dfeb3efcb5d914667ee38887d8, are complete: 25 successful checks and six expected skips. Unity run 38770986224 passes all four Editor versions, the SINGLE_THREADED modes and package export. Repo Lint, source compilation, compiler controls, contract suites, generator/oracle suites, documentation and Cursor review also pass. All six acquired Unity jobs confirm healthy cleanup and successful license/lock release.

The passing 2021.3 job contains two fresh Native Crash Reporting events. Its results and cleanup pass, but those reports remain unexplained; CI success does not establish native-safety acceptance. The details are recorded in #343. All three target issues remain open for their broader acceptance requirements.

Fresh native discovery reports on the final head

The Unity 2021.3 job logs two reports on 2026-10-15:

• 17:23:18 UTC, OdinMigrationBackupRecoveryTests/unity.log:562: UNKNOWN native condition in RuntimeMethodInfo.GetMethodFromHandleInternalType_native, followed by RuntimeType.GetMethods, NUnit Reflect.HasMethodWithAttribute and DefaultSuiteBuilder.CanBuildFrom.
• 17:24:49 UTC, OdinMigrationDictionaryApplyIntegrationTests/unity.log:4142: UNKNOWN native condition in array allocation, then ListBuilder.Add, RuntimeType.GetMethods and the same NUnit discovery path.

Passing fixture results are written after both reports. The job later emits four fatal/Mono-pattern diagnostic annotations referring to those two events, yet its test-result and final gates conclude success. These are two reports, not six separate events. No report or annotation was suppressed. The prior four reports on 240d9da8 remain retained as well.

The current scene sibling test passes both False and True variants. That narrows the evidence but does not classify or fix the preceding 9ef989bd mismatch. No scene canonicalizer source was changed for this session. Keep the native-report cause and scene assertion investigation open.

Original artifact verification and next diagnostic

The downloaded unity-2021.3.45f1-editmode artifact 11994493758 matches GitHub SHA-256 99c4e3654ef76b52a73b9d9d18b5beb12bf20ceb6ef27931aea403df45234324. Its 16 entries contain logs, NUnit XML and toolchain/startup records; none is a native dump or mono_crash report. The two original fixture logs contain one Native Crash Reporting header each, at lines 560 and 4140; the UNKNOWN messages follow at the previously recorded lines 562 and 4142.

Neither report includes a native stack, exception code, fault address or the specific type being reflected. The managed stacks localize the operation to NUnit discovery. They do not identify its cause. Source inspection also confirms that catastrophic-pattern matches emit diagnostic annotations while the result gate separately validates NUnit XML; this explains the successful check status alongside the reports.

A controlled Unity 2021.3.45f1 reproduction needs to capture the reflected type and native exception details or a dump, with the same package inputs and unchanged fixture assertions. That evidence is required before classifying these reports. The verified archive inventory and log hashes are retained in progress/.artifacts/targeted-20261015/native-artifact-inventory-3fdddcf7.json. No raw licensed log content is copied into this issue.

Diagnostic investigation handoff

The available Unity MCP host is SPICY, running Unity 6000.4.6f1. The affected CI runner is ELI-MACHINE with Unity 2021.3.45f1. The bridge host has neither that exact Editor executable nor the checked native debugger installation, so a bridge test would not reproduce the affected environment.

The CI harness already records bounded process identity and matching Windows failure events for configure failures. A possible next step is to retain that diagnostic evidence for guarded test processes as well, including processes that write passing XML after a native report. This was investigated only; no harness change or new diagnostic run was implemented. Preserve the existing assertions, native-report evidence and result acceptance when adding capture.

Verified current-head native results

The following native jobs pass on 3fdddcf74e82f2dfeb3efcb5d914667ee38887d8. Counts are passed / failed / skipped as reported by NUnit.

All five Editor-version jobs also pass six isolated EditMode batches of 9, 22, 32, 23, 7 and 32 cases. The seven dictionary apply/reload variants, 0 through 6, are explicitly present as passing stream results in each completed log. All four regular Editor-version jobs additionally pass 82 WProto-only Standalone cases each, with zero failures/skips. The SINGLE_THREADED player receipt identifies IL2CPP, Release, high stripping, development=False and the required define.

Package export smoke and its aggregate gate also pass. All six acquired jobs confirm healthy final license cleanup and lock release. The 2021.3 log contains two Native Crash Reporting events; the other five completed job logs contain none. Both scene sibling variants pass on the current 2021.3 head, but this passing run does not explain the preceding file-ID mismatch. That prior assertion and all native reports remain unresolved.

The current generator job passes both Release oracle suites (1,330 v3 and 1,298 v2 cases, zero failures/skips) and 879 analyzer cases. The compiler-bound safety report is independently verified on #637. These results do not explain the retained native reports, resolve the prior scene assertion, or establish real-consumer acceptance. The remaining scope below is unchanged.

Session wrap-up: final PR and unresolved acceptance

The final session commit is 3fdddcf74e82f2dfeb3efcb5d914667ee38887d8 in PR #1015. The PR base matches current main at e70bd313ccab2e8920ac0bfc98b6d64891416a25. The final worktree is clean. Final-head CI is complete: 25 successful checks and six expected skips. The native reports and broader acceptance requirements remain open.

The semantic policy implementation is in 8be06b98b085dd3283da1d5524008564029b3631. Its first hosted documentation build failed because the new contributor guide linked to a workflow file excluded from the documentation site. The final commit changes only that guidance to plain text. The corrected strict MkDocs build, documentation links and both preflight modes pass locally. The final-head hosted documentation build also passes; all remaining final-head checks now pass. The failed intermediate docs run remains recorded; it is superseded, not reclassified as a pass.

The preceding completed hosted matrix, Unity run 38727441238 at preceding head 9ef989bde89e87a9a81ad4eac14538f54dc8a1cd, is not green: 22 checks succeed, six skip, and three fail (the Unity 2021.3 job and its two aggregates). The sole reported failing case is SceneCanonicalizerIntegrationTests.AddedSiblingsUnderPrefabParentsBakeAndReloadConsistently(False): expected component fileID 954953484, actual 954953483. Its broad EditMode result is 6,482 total, 6,004 passed, one failed and 477 skipped. The isolated migration fixtures, including the seven reload/apply cases, pass; PlayMode, Standalone and the 82-case WProto-only player result also pass. The other Unity versions, SINGLE_THREADED modes and package export pass. All six acquired jobs confirm healthy cleanup and successful license/lock release. The scene assertion remains unresolved; it was not changed or rerun to obtain a passing result during wrap-up.

The semantic policy commit changes the safety policy tool, its controls, workflow SDK setup and contributor documentation. Runtime enum conversion, codecs and the three shipped compiler-input DLLs are unchanged from the earlier implementation/evidence below. The compiler-bound safety suite passes 155 controls and the real 63-site scan; syntax/equivalence, documentation, spelling, workflow lint and both changed-file preflight modes pass.

The four previously recorded Native Crash Reporting events on 240d9da8 remain unexplained. The fetched preceding-head 9ef989bd 2021.3 and 2022.3 job logs contain no Native Crash Reporting event, but this does not explain those prior reports or establish native-safety acceptance. Earlier logs, failed runs and inconclusive measurements remain retained.

Keep this issue open. Full facade/type acceptance, qualified paired player performance/allocation and code-size evidence, the native-report cause, and coordinated major-release retirement of runtime protobuf-net DLLs remain incomplete. Real Shiro, DoxReloaded and IshoBoy projects and retained saves remain unavailable, as previously confirmed. No full migration or release acceptance is claimed.

Earlier implementation and native-report evidence

The following completed-matrix statements refer to 240d9da8, as identified in that evidence; they are historical and do not describe the final head.

Fresh current-head native discovery reports

All 31 checks on this head are complete: 25 success and six expected skips. Unity run 38700832679 passes all four editor versions, PlayMode, Release IL2CPP Standalone, WProto-only Standalone, SINGLE_THREADED modes and package export. All six acquired jobs confirm healthy cleanup and successful release. All four PR feedback surfaces were checked; no comments, review threads or failed checks remain. This verifies CI, not the broader native-safety or real-consumer acceptance.

PR #1015, head 240d9da8ada88b0e996af0f23ee1a4ed55eb1562, still emits native reports in the passing Unity 2022.3 job 116308481761. Freshly fetched logs contain three Native Crash Reporting events on 2026-10-15:

• 08:09:49 UTC: UNKNOWN native condition in array allocation, then RuntimeType.GetMethods, NUnit Reflect.HasMethodWithAttribute and DefaultSuiteBuilder.CanBuildFrom.
• 08:12:19 UTC: UNKNOWN native condition in array allocation, then NUnit MethodWrapper.GetParameters and test-method signature discovery.
• 08:13:16 UTC: UNKNOWN native condition in RuntimeMethodInfo.GetMethodFromHandleInternalType_native, then RuntimeType.GetMethods and NUnit fixture discovery.

The passing Unity 2021.3 job 116308481889 contains another report at 08:37:59 UTC on 2026-10-15. It reports an UNKNOWN native condition in RuntimeMethodInfo.GetMethodFromHandleInternalType_native, then RuntimeType.GetMethods and NUnit Reflect.HasMethodWithAttribute / DefaultSuiteBuilder.CanBuildFrom. This makes four fresh reports on the current head.

Execution continues after each report. EditMode, PlayMode, Release IL2CPP Standalone and the 82-case WProto-only Standalone result pass. The acquired job confirms healthy cleanup and successful release. These outcomes do not explain the reports or establish native-safety acceptance. No report was suppressed. The completed 6000.5, 6000.6 regular, SINGLE_THREADED and package-export logs contain zero Native Crash Reporting events. All jobs are now complete. Sanitized stack receipts are retained; raw licensed logs are not copied here.

Checked enum codecs and private migration support

PR #1015 at 240d9da8ada88b0e996af0f23ee1a4ed55eb1562 replaces the remaining enum memory-access operations with checked single-value spans and adds generated private/protected dictionary bindings for supported partial owners. It also fixes selected-fixture MSBuild item expansion and adds runtime fixture scopes for local iteration.

The final Release oracle suites pass 1,330 protobuf-net v3 and 1,298 v2 cases with no skips. Exhaustive byte-pattern and seeded all-width enum controls preserve protobuf bytes; a deliberate signedness mutation fails the new oracle. Native Unity 6000.4.6 passes 13 formatter, 79 enum-helper and 44 live-dictionary cases. All seven private-readonly reload/apply cases pass before the final factory-name-only amendment; those subject names are unchanged. The full normal local compiler matrix and affected final Editor variants pass.

Warm Editor allocation controls record zero enum-conversion allocations across all eight widths. The safe candidate remains slower than a copied Unsafe baseline: best 2.23–2.85 ms versus 0.78–0.83 ms per 100,000 calls. These calibrated Editor samples include delegate/facade overhead and do not establish player or broad performance acceptance. The negative result is retained in the commit.

Keep this issue open for the full facade/type matrix, paired player performance and code-size evidence, unresolved native discovery reports, actual Shiro/DoxReloaded/IshoBoy projects and retained saves, and coordinated major-release removal of runtime protobuf-net DLLs. The projects and saves remain unavailable as previously confirmed. Passing CI does not explain the previously recorded native reports.

Previous scope and evidence

Calibrated warm readonly-consumer read measurement

A further native measurement on the unchanged PR #1014 head dcf5edb1 qualifies this new path on Unity 6000.4.6f1 EditMode. The loaded-code gate requires the new consumer contract and a successful explicit object read with exact identifier 42 and Int64 sequence 9007199254740993. The baseline is an isolated protobuf-net 3.2.56 RuntimeTypeModel with matching tags 5/11 and zero defaults, using ReadOnlyMemory input. Its bytes match the generated 11-byte payload and both read forms restore exact values; RuntimeTypeModel.Default is not used.

Profiler GC.Alloc controls record 128 fresh-box allocations and zero preboxed assignments over 128 calls, repeated three times. Reused-buffer typed and erased writes and typed reads record zero allocations in all three trials. Erased struct reads record 128 allocations per 128 calls, consistent with the returned box. Matching protobuf-net typed/erased reads also record 0/128 allocations.

The timer runs at 10,000,000 Hz; its observed minimum positive delta is one tick. A 20 ms sleep control measures 30.9022 ms. Every workload cell is positive and every decoded-value check passes. Calls use direct delegates, with their overhead present in both arms; these numbers do not estimate pure codec speedups.

The matching string closure was measured separately with identifier café/中, the same exact Int64 value, and a 20-byte payload. Its isolated model uses the matching null string default. Bytes and both decoded values match. The current-code gate and allocating/preboxed controls pass; the same 10 MHz clock observes a one-tick minimum delta and a 31.6971 ms sleep control.

All three allocation trials agree. These string counts are consistent with the returned string and, for erased reads, an additional struct box. The zero-allocation typed-read observation above applies to the integer closure.

This is additional warm Editor evidence for these two flat consumer contracts. It does not establish cold-start, every consumer shape, Release-player allocation or broad native safety. Full probe source and JSON are retained under progress/.artifacts/goal-targeted-20261014/continued-readonly-native-performance.*. The wider acceptance below remains open.

Current consumer fixes and unresolved native reports

PR #1014, candidate dcf5edb15e7219a5cbbba75226c1c65896471e39, fixes generated constructors for readonly generic structs and explicit concrete protobuf reads through object or another assignable unregistered declaration. Generated runtime codecs serve those reads without reflection-based member discovery; registered contracts, declared roots and collection marshals retain precedence. Unsupported and malformed requests keep the public serialization failure contract.

The new consumer type lives in a different native Unity assembly from its caller. Native PlayMode passes all 12 public facade/JSON controls with no skips; the existing protobuf behavior fixture passes 7/7. The two protobuf-net oracle suites pass 1316 v3 and 1284 v2 cases with no skips, retaining exact bytes and both read directions for integer/string generic identifiers and Int64 edge values. All 31 checks on dcf5edb15e7219a5cbbba75226c1c65896471e39 are complete: 25 success and six expected skips. Unity run 38664556987 passes all four editor versions, single-threaded modes, package export and all aggregates. Every acquired path's return, classification, release and confirmed-cleanup gate passes. All four feedback surfaces were checked; no unresolved comments or review threads remain.

The current-head 2021 job 116193839287 completed every selected mode and confirmed cleanup, but its freshly fetched log contains one native report at 2026-10-15 01:41:52 UTC. It reports an UNKNOWN native condition in array allocation / MonoCustomAttrs.GetPseudoCustomAttributes, followed by NUnit TypeWrapper.IsDefined and DefaultSuiteBuilder.CanBuildFrom. Test execution continues. No repository test/control contains the literal Native Crash Reporting marker. This is fresh unresolved native evidence on dcf5edb1. Execution continues and tests pass, while the cause and process-fatal significance remain unproved.

The merged-main commit 0b216db9182495168b515a00b6fa49e8873096ea now has all 44 checks complete with success or expected skip. Unity run 38655457751 passed the full matrix, but fresh logs still contain three native reports during NUnit discovery:

• 2022 job 116164123800: two reports at 2026-10-14 23:49:07 and 23:52:21 UTC, in reflection method discovery and MethodWrapper construction.
• 2021 job 116164123857: one report at 2026-10-15 00:00:48 UTC, in reflection method discovery.

Execution continued and all six acquired jobs confirmed healthy cleanup and successful release. Those outcomes establish CI and enrollment cleanup, not a causal explanation or native-safety acceptance. Sanitized stack receipts remain retained; raw licensed logs are not copied into this issue.

Keep this issue open for the remaining facade/type matrix, stable performance/allocation/native-safety acceptance, actual Shiro/DoxReloaded/IshoBoy projects and retained saves, and the coordinated major release removing runtime protobuf-net DLLs. The user reconfirmed the real projects/saves are unavailable. Existing native, canonicalizer and earlier CI failure evidence remains unresolved unless its actual cause is established.

Historical evidence

Verified merge and native report qualification

PR #1013 merged on 2026-10-14 as 0b216db9182495168b515a00b6fa49e8873096ea. All 32 checks on reviewed head 702862c46f94e1e1a128858b45060ee8bbe1deaa completed with success, expected skips, or the neutral Bugbot review. Its only review thread is resolved. This establishes PR CI and landing, not the wider acceptance below.

A fresh read of the passing Unity 2021 job 116065749430 still finds four native reports. They occur at 22:12:16 and 22:14:40 UTC in NUnit duplicate-name discovery (dictionary Resize/Initialize), at 22:17:59 in reflection-based fixture discovery, and at 22:32:07 in method-name discovery before the Standalone build. Execution continues afterward and licensed cleanup is confirmed healthy. These reports therefore remain unresolved; they are neither a proven shutdown-only event nor explained by passing XML. No report was suppressed or accepted as a serializer safety result.

Keep this issue open for the full consumer/facade, calibrated performance/allocation, native-safety, retained-save, and coordinated major-release requirements. The required real consumer projects and saves remain unavailable in the existing session evidence.

Current published candidate and calibrated evidence

PR #1013 now contains 702862c46f94e1e1a128858b45060ee8bbe1deaa. It includes the earlier temporary-assembly retirement changes and calibrated warm protobuf comparisons. Both benchmark contracts use unpacked integer arrays; the generated arm calls WProtoFacade directly. A timer control runs first, correctness runs before warmup and after samples, and each of six workloads retains 32 counterbalanced observations per arm.

Native Unity 6000.4.6 passed both final benchmark cases in 397.1 seconds. All six comparisons exceeded the fixed 3% spread limit and report inconclusive speedups. This supplies reproducible raw evidence, not throughput acceptance. The earlier synchronous run failed on a bridge transport log after recording its samples. The final coroutine run passed in saved NUnit XML; its CLI request still timed out and its status remained stale until cleared after verifying completion. The measurement environment was restored and the editor requested to reload afterward.

Native consumer-model, generic-contract, facade and cross-assembly fixtures passed 13, 5, 33 and 4 cases respectively, zero skips. These 55 synthetic controls do not substitute for real consumer acceptance. A new live-recovery test used a concrete Dictionary local and prevented isolated compilation of the converted field. Using the shared IDictionary interface resolves that caller. Native live-dictionary controls pass 25/25 and isolated compilation passes 9/9 in 296.9 seconds. The exact same caller failed the preceding Unity 2021 and 6000.6 jobs; both confirmed healthy license cleanup. Fresh published-head CI remains required.

Keep this issue open. Wider facade/consumer compatibility, stable throughput, broader allocation and native-safety evidence, the Unity 2022 cleanup floor, retained saves and the coordinated major release remain. Shiro, DoxReloaded and IshoBoy projects and saves remain unavailable, as confirmed by the user. The earlier narrow allocation and timing samples below remain limited to their stated scopes.

Current session evidence and remaining acceptance

PR #1013, candidate 342611612d2b58bf873c0287d5c6ffd0164f35d0, retires temporary consumer assemblies before deleting their compiler inputs. The fixture checks that the package assembly is present and the temporary consumer is absent from the compilation graph before deletion. Readiness instructions remain in top-level test iterators across reloads.

Native Unity 6000.4.6 passed six migration cases in the full batch. The live-success case exposed an incorrect native-asset reference kind, triggered recovery, and then passed its focused rerun after correction (180.7 seconds). Both failed and passing XML are retained locally. All fixture folders were removed, and the host Editor log contains no CS2001. This does not establish the Unity 2022 floor or resolve the earlier native reports.

The full generator suites pass 1,308 v3 and 1,276 v2 cases, with zero skips. Full local compilation variants and final preflight passed. A calibrated native editor sample compares one 15-byte Vector3Surrogate reusable-buffer write: a 20 ms sleep control measured 21.9862 ms; three alternating trials used 262,144 generated calls and 131,072 oracle calls. Best samples are 284.84 ns generated and 609.54 ns protobuf-net, a 2.14x ratio including loop/result checks. Wire bytes matched. This is one warmed editor payload, with no allocation, cold-start, or player acceptance claim.

A separate allocation probe observed an actual domain reset through an AppDomain marker before serialization. Its GC.Alloc controls recorded 128 fresh boxes and zero preboxed assignments. Three alternating batches of 128 warmed reusable-buffer writes recorded zero events for both generated and protobuf-net paths. This establishes current-thread event counts for that payload only; it does not establish byte sizes, cold-start, broader workloads or Release-player allocation. The editor was requested to reload again afterward.

New-main Unity 2021 job 115991781529 on 14d9b25080c9bce9fe5bea537b8542d4c35e93f1 failed EditMode with one SceneCanonicalizer prefab-sibling fileID mismatch. It also emitted native reports in Unity test-name duplicate discovery and the test-naming validation fixture, followed by continued execution. PlayMode, Standalone and WProto-only Standalone reported no failed cases. Logs are retained. These are separate failure evidence, not current-candidate validation; no passing rerun or shutdown-only classification is claimed.

Keep this issue open for broad consumer/facade compatibility, calibrated coverage across workloads, allocation and native-safety evidence, Unity 2022 cleanup confirmation, and the coordinated major release. The user reconfirmed Shiro, DoxReloaded, IshoBoy and retained saves are unavailable. Repository clones used for the source-free enrollment audit do not supply those projects or saves. Current-head CI and review acceptance remain pending.

Previous landed scope and evidence

Landed scope and remaining work

PR #1005 merged on 2026-10-14 at 06:06 UTC as 13f569af. Its reviewed head was 00cc8bda5079efe96bead1d322dc1bb28284ba42; the merged tree is identical. All 32 PR checks completed with success or expected skips, including Unity CI Success, Repo Lint and Contract Suites. All 14 review threads were resolved. The complete Unity matrix passed all four editor versions, single-threaded modes and package export; every licensed job confirmed healthy cleanup. This establishes PR CI and landing, not the broader native-safety or real-consumer acceptance below.

Keep this issue open. Remaining work:

• Complete consumer generic, inheritance, immutable, and JSON/protobuf facade compatibility coverage.
• Investigate the retained NUnit/Mono native reports, native allocation warnings, and exit/result discrepancies; retain dumps and event timing. The 2022 job's passing result does not explain its native report.
• Fix temporary consumer assembly cleanup so Unity 2022 removes old graph inputs before source deletion, with controls proving absence of CS2001 while retaining real reload and recovery.
• Establish calibrated throughput/allocation and native-safety evidence.
• Validate real Shiro, DoxReloaded and IshoBoy players and retained IshoBoy SQLite/settings saves when the projects/data are available.
• Coordinate the major release that retires runtime protobuf-net DLLs after compatibility acceptance.

Existing evidence, reproduction links, accepted wire policy and original requirements below remain applicable.

Implementation and prior evidence

Implementation is in PR #1005, current published head 00cc8bda5079efe96bead1d322dc1bb28284ba42. This issue remains open.

Accepted wire policy: retain generated/protobuf-net v3 writes and require value compatibility with protobuf-net v2. For Shiro's empty-string dictionary values, v2 omits the value field while v3/generated output explicitly encodes it; both readers must retain the empty string. This accepted exception supersedes the universal v2/v3 byte-equality wording in the original design below.

Local generator suites pass 1,301 cases against v3 and 1,269 against v2, with no skips. Relevant compile variants have zero warnings/errors; native migration compilation passes 9/9. The exact-candidate central audit is complete with six repositories, 116 jobs and zero findings. preceding-head Unity run 38486518526 is incomplete; its normal 6000.6 job failed. Earlier-head 6000.5 completed all modes successfully with confirmed license cleanup.

The earlier 2021.3 job completed under the existing artifact policy, but native crash reports appeared during execution followed by continued execution, and PlayMode exited 2 despite nonfailed XML. This remains an unresolved native-report and exit/artifact discrepancy, not a proven shutdown-only event or completed safety acceptance. The failed compiler-layout runs are retained as failure evidence; the SDK discovery repair has a subsequent real 6000.5 success.

Remaining acceptance includes broad consumer generic, inheritance, immutable and JSON/protobuf API compatibility; safety and calibrated performance evidence; real Shiro, DoxReloaded and IshoBoy player deployments and retained-save checks; and coordinated major-release retirement of runtime protobuf-net DLLs. The real Unity projects and retained IshoBoy SQLite/settings saves remain unavailable here, as previously confirmed by the user.

The preceding 65342745 2021.3 job passed its isolated compiler, EditMode, PlayMode and WProto-only modes, but Standalone failed MatchColliderToSpriteTests.UpdatesColliderWhenSpriteChanges during teardown on Unity's JobTempAlloc warning about allocations older than four frames. Job 115588720317 reported 17,773 total / 16,006 passed / one failed / 1,745 skipped and confirmed healthy license cleanup. This native allocation warning remains unresolved; no log suppression or passing-rerun acceptance was added.

The published 4e957c8d normal 6000.6 job 115601950163 failed EditMode because the new import-verification fixture checked values while the Editor still reported import in progress. That fixture must wait for editor readiness before positive and negative value checks; the production guard remains required. PlayMode also exited 0xC0000005 / STATUS_ACCESS_VIOLATION despite nonfailed XML (18,583 total / 18,542 passed / 35 skipped / six inconclusive). Native cause and timing remain unresolved. Standalone reported 17,771 total / 16,017 passed / zero failed / 1,731 skipped; WProto-only passed 82/82. License cleanup was confirmed healthy. Neither artifact acceptance nor a future passing rerun completes native safety acceptance.

Prior-head Unity run 38507451398 failed migration backup writes in both 6000.6 modes and subsequently in 2021.3 and 6000.5. The compact backup layout above addresses that shared failure; superseded jobs are not final-candidate acceptance.

The preceding 6000.6 single-threaded job also reported STATUS_ACCESS_VIOLATION after the compiler fixture's 9/9 result and after nonfailed PlayMode XML. Normal 6000.5 reported only the import-verification test failure among these new observations. Both jobs confirmed healthy license cleanup. The readiness fix does not classify or repair the native crashes.

The preceding 215ce1c3 run failed full EditMode in 2021.3, 2022.3, 6000.5 and single-threaded 6000.6: migration fixture setup repeatedly waited 60 seconds while EditorApplication.isUpdating stayed true, exhausting the 40-minute action deadline without root NUnit XML. The isolated compiler passed 9/9 in each job, and all four jobs confirmed healthy cleanup. These are failed runs, not accepted compiler-only coverage. The current head runs each of four migration fixtures in a fresh editor process, requires passing XML for every named fixture, and still requires the broad suite's independent root result. Local shipping-script controls pass 29 isolation and 52 exit/XML cases.

The readiness and isolation changes do not classify or repair the previously retained native crashes, allocation warning, or exit/artifact discrepancies. Real-project/save and major-release acceptance remains outstanding.

Published 5f99cef7 replaces AppDomain.GetAssemblies() with Unity's loaded-assembly API on 6000.6 and newer. The preceding export and both 6000.6 jobs failed the strict warning gate on UAC0005 in OdinMigrationApplySnapshot; those failures are retained, and cleanup was healthy. The preceding 2022.3 job reached the isolated apply fixture but Bee compiled stale Assembly-CSharp inputs after temporary source deletion, emitting CS2001 before rebuilding its graph; cleanup was healthy. The fixture now uses a dedicated temporary consumer assembly. All three native reload/apply cases pass with that layout (88.1, 73.4 and 68.4 seconds); the 2022.3 fix still needs current-head CI confirmation.

Native Unity 6000.4.6 also passes all 26 record/scene controls, including exact Int64 limits and 2^53 + 1, exact deadline ticks, sole-saved-scene restoration, and protection of later temporary-scene edits. Both new review findings were answered with these measurements and resolved without changing the passing record or scene behavior. Hosted Local Gates, Repo Lint, generator and docs passed at the preceding head. Current local default Editor/EditorTest builds, preflight, spelling, member/comparison checks and strict docs pass. The exact new candidate audit is complete: six repositories, 116 jobs, zero findings. No current-head full matrix, merged-main, native-safety, or real-consumer acceptance is claimed.

Original design

Problem (one paragraph)

protobuf-net v3's runtime engine is fundamentally incompatible with IL2CPP: it constructs serializers by
reflectively instantiating internal closed generics (ConcreteStub, ListSerializer,
StructValueChecker) via MakeGenericType, which IL2CPP cannot AOT-compile, and it calls the
IL2CPP-unsupported RuntimeParameterInfo::GetTypeModifiers icall during model build. This is
maintainer-confirmed (protobuf-net#699/#792/#1025/#1190); the real protobuf-net AOT story ("generators") is
still not shipped. No link.xml/[Preserve]/AotHelper manifest can fix it (the failing generics are
internal and reflectively reached). Yet we require runtime protobuf serialization in shipped IL2CPP
players (player data) and must stay byte/wire-compatible with data already written by protobuf-net —
v2 and v3 both, because this is a library and clients in the wild have persisted data with either. At
CompatibilityLevel 200 v2 and v3 emit the same wire format, but we treat that as a claim to prove, not
assume: the conformance suite uses a dual oracle (protobuf-net v2.4.x and v3.2.x) and fails if they
ever disagree on a contract we ship.

Why an in-tree source generator is the right answer (not a fallback)

The decisive property: a Roslyn source generator emits static serializer code at the compilation that
references the closed type — including the consumer's assembly. So Deque gets a real,
statically-dispatched serializer in the consumer's build, which IL2CPP AOT-compiles normally. This is the
only approach that solves the redistributable-generics problem; precompile and v2-downgrade cannot, by
construction. It also keeps the perf wins (generated straight-line code beats reflection/ref-emit on cold
start and matches it warm), and lets us delete the vendored protobuf-net.dll + protobuf-net.Core.dll
from the runtime entirely (they remain only in the test assembly, as the conformance oracle).

Goals / non-goals

Goals

• Byte-for-byte wire compatibility with protobuf-net v2.4.x and v3.2.x @ CompatibilityLevel 200 for every
  contract the package ships, proven by a differential test against both vendored oracles (and a committed
  golden-byte corpus so the guarantee survives even if the oracles are later removed).
• Zero runtime reflection / zero MakeGenericType / zero ref-emit → clean IL2CPP + future NativeAOT.
• Drop-in for the existing Serializer.ProtoSerialize / ProtoDeserialize facade (no consumer API
  break; same method signatures).
• Support consumer-defined [ProtoContract] types and consumer closed generics with no per-consumer manual
  registration (generator-driven).
• Equal-or-better throughput and allocation vs protobuf-net v3 warm; dramatically better cold-start.

Non-goals (initial release)

• Full .proto schema import/export, gRPC, DynamicType, AsReference (graph/reference tracking),
  runtime-mutable models, Serializer.Merge onto pre-populated graphs. (Enumerate any of these the package
  actually uses during the inventory phase; the grep found none of AsReference/DynamicType.)
• CompatibilityLevel 240/300 encodings (not used; default is 200).

Architecture (MemoryPack/LightProto-style, adapted to protobuf wire format)

1. Roslyn IIncrementalGenerator (WallstopStudios.UnityHelpers.Proto.Generator, netstandard2.0 DLL,
   shipped as a Unity RoslynAnalyzer-labelled asset so it runs on the package and consumer assemblies).
   • Discovers types annotated [ProtoContract] (reuse protobuf-net's attributes for source-compat, OR
     introduce thin aliases — decide in the inventory phase) and surrogate registrations.
   • For each type, emits a partial static formatter implementing IWProtoFormatter:
     void Write(ref WProtoWriter w, in T value) + T Read(ref WProtoReader r), as straight-line code over
     the type's [ProtoMember] fields (tag + wire-type constants computed at generate time).
   • For generic [ProtoContract] types, emits an open-generic formatter Formatter whose element
     access goes through WProtoFormatterProvider.Get() — static generic dispatch, AOT-friendly.
2. WProtoFormatterProvider — a static registry mapping T → IWProtoFormatter. Generated
   per-assembly [ModuleInitializer]/RuntimeInitializeOnLoadMethod registration code populates it for every
   discovered closed type (incl. consumer closed generics seen at the consumer's build). Built-in formatters
   for primitives, string, byte[], enums, Nullable, List/arrays/dictionaries, and the
   bcl.proto types (DateTime/TimeSpan/Guid/Decimal at Level 200).
3. WProtoWriter / WProtoReader — ref struct over Span / IBufferWriter: varint
   (little-endian base-128), zigzag, fixed32/64, length-delimited with back-patched lengths (two-pass or length-prefixed
   scratch), tag read/skip-unknown-field. This is the hand-written wire core (~1 file, heavily tested).
4. Facade integration — Serializer.ProtoSerialize/ProtoDeserialize (Serializer.cs lines
   ~2125/~1665) dispatch to WProtoFormatterProvider.Get() instead of ProtoBuf.Serializer. The existing
   special-collection wrapper marshalling (Deque/CyclicBuffer/SparseSet → *ProtoWrapper) is preserved
   conceptually but the wrappers become generated formatters.

Wire-format conformance requirements (the exhaustive checklist — Level 200)

Reproduce protobuf-net v3 exactly for:

• Field key (fieldNumber << 3) | wireType; wire types 0=varint, 1=64-bit, 2=length-delimited, 5=32-bit.
• Scalars (DataFormat.Default — the package sets no DataFormat): int32/int64/uint32/uint64/bool/enum →
  varint; float → fixed32; double → fixed64; string/bytes → length-delimited. (No ZigZag/FixedSize/TwosComp
  observed; confirm in inventory and emit accordingly if any appear.)
• Repeated fields: protobuf-net default is unpacked (repeated tag+value) unless IsPacked=true
  (none found). Match this — do not pack by default (differs from proto3).
• [ProtoInclude(tag, subType)] inheritance (AbstractRandom, tags 100–116): the concrete subtype is
  written as a length-delimited field at its include tag on the base message, containing the subtype's own
  members; base members written at their tags. Reproduce the nesting + ordering byte-for-byte.
• Surrogates: apply the registered real→surrogate transform at write, surrogate→real at read; the
  surrogate's [ProtoMember] tags define the wire shape (FastVector3Int's deliberate out-of-order
  3=hash/4=z must be preserved — ProtobufUnitySurrogates.cs ~370).
• Nullable: present iff HasValue (e.g. AbstractRandom._cachedGaussian double?,
  UnityRandom._seed int?); absent field on read → null.
• IgnoreListHandling (Deque) and OverwriteList=true (Serializable{HashSet,Dictionary,SortedDictionary}):
  reproduce as message-shaped (not list) and replace-on-read semantics respectively.
• bcl.proto Level 200: DateTime/TimeSpan → bcl sub-message (zigzag value + scale enum [+ kind]); Guid →
  bcl {lo: fixed64, hi: fixed64}; Decimal → bcl {lo: uint64, hi: uint32, signScale: uint32}. Only
  implement the ones actually used (inventory).
• Default-value omission: protobuf-net omits members equal to their declared/implicit default unless
  IsRequired/explicit default differs — match its emit rules precisely (this is a common byte-diff source).
• Field ordering: protobuf-net writes members in ascending field number. Match.

Consumer extensibility & IL2CPP generics (the key advantage, spelled out)

• A consumer adds [ProtoContract] struct Foo {…} and serializes Deque. The generator runs on the
  consumer's assembly, sees Foo and the Deque usage, emits Formatter + registers
  Deque's closed formatter. IL2CPP AOT-compiles them because they're real static code referenced from
  the consumer's call site — no runtime MakeGenericType, no manifest.
• Fallback: if a closed type is somehow unseen at build, Get() throws a clear, actionable exception at
  the call site (naming the type + how to annotate), not an opaque ExecutionEngineException.

Differential conformance test strategy (how we prove byte-compat)

• Keep vendored protobuf-net v2.4.x and v3.2.x in the test assembly only, as a dual oracle
  (cross-assembly-aliased so both load side by side). Assert WProto bytes == v3 bytes == v2 bytes; any
  v2/v3 disagreement on a shipped contract is itself a finding to resolve before release.
• For every supported type, a property-style corpus (edge values: empty, max/min, negative, large
  collections, nested, polymorphic across all 17 PRNG subtypes, null/non-null Nullable, default-valued
  members): assert WProto.Serialize(x) bytewise == ProtoBuf.Serializer.Serialize(x), and
  cross-deserialize both directions (WProto.Deserialize(protobufNetBytes) and vice-versa) → value-equal.
• Reuse/upgrade the existing 48 ProtobufSerializationTests as the behavioral floor; add the byte-equality
  layer on top. A golden corpus of pre-serialized v3 bytes (committed as fixtures) guards against future
  drift even if the vendored oracle is later removed.
• These tests run on Mono (editmode/playmode) where protobuf-net v3 works; the runtime ships only WProto,
  so the IL2CPP standalone leg exercises WProto exclusively → the leg that is red today goes green.

Migration & rollout

1. Inventory & freeze the contract surface (types, tags, surrogates, DataFormat/packed usage, bcl types
   actually used, any AsReference/DynamicType/Merge — none found so far). Output: a definitive
   conformance matrix.
2. Wire core (WProtoWriter/Reader) + unit tests (varint/zigzag/fixed/length round-trips).
3. Hand-written formatters for the package's own closed types (no generator yet) + differential tests
   green on Mono. Proves the wire model before investing in codegen.
4. Source generator replacing the hand-written formatters; generator snapshot tests + the same
   differential suite.
5. Facade swap behind a define (WALLSTOP_PROTO) for one release: WProto on IL2CPP, protobuf-net on Mono,
   differential-tested equal — then flip default and remove the runtime protobuf-net DLLs.
6. CI: standalone IL2CPP leg green with WProto; document the consumer annotation story in the README.
   Interim before step 5: gate the protobuf IL2CPP tests behind !ENABLE_IL2CPP + document the Mono-only
   limitation so the current branch merges green.

Performance goals

• Warm throughput ≥ protobuf-net v3 (generated code, no per-call model lookup beyond a static field read).
• Cold start ≫ better (no model build / no ref-emit).
• Zero allocations on the write path for Span/IBufferWriter overloads; pooled scratch for length
  back-patching. Validate with the existing performance test asmdef + the Unity Profiler MCP.

Risks & mitigations

• Subtle wire mismatches (default omission, packed/unpacked, bcl scale) → the byte-level differential
  suite + golden corpus catch every one before release; develop step 3 against the oracle, never blind.
• Generator complexity / Unity analyzer packaging → validate the RoslynAnalyzer round-trip early
  (a trivial generated type) on all three Unity versions (2021/2022/6000) before building the real generator.
• Scope creep (AsReference/DynamicType/gRPC) → explicitly out of scope; assert none are used; fail the
  build if a contract uses an unsupported feature (generator diagnostic).
• Maintenance of a serializer → bounded: the wire format is frozen (Level 200), the corpus pins behavior,
  and we own the AOT story end-to-end instead of tracking an upstream that has no IL2CPP path.

Effort & sequencing

Large (multi-week). Independent of the test-runtime/PlayMode tracks; lands on its own branch. Ship value
incrementally: steps 1–3 already deliver an IL2CPP-safe serializer for the package's own types (covers the
player-data case for built-in contracts); steps 4–5 generalize to consumer types and remove the dependency.