[record_use] (De)serialization context

[dcharkes]

Organize the serialization/deserialization with a context object:

• [record_use] Implementation: Organize the normalization in semantic/syntax mapping #3106

[github-actions]

PR Health

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?
record_use	Breaking	0.4.2	0.5.0-wip	0.5.0-wip	✔️

This check can be disabled by tagging the PR with skip-breaking-check.

License Headers ✔️

// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/jni/test/debug_release_test.dart
pkgs/objective_c/example/command_line/lib/main.dart
pkgs/objective_c/lib/src/ns_input_stream.dart

This check can be disabled by tagging the PR with skip-license-check.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

[coveralls]

coverage: 78.184% (+0.006%) from 78.178%
when pulling c9d07a1 on record-use-de-serialization-context
into 938b861 on main.

[goderbauer]

I am trying to relate this back to the code. Where would I find the implementation of the syntax layer and semantics layer? Can you leave some breadcrumbs in the doc?

[goderbauer]

What constants and recordings is this referring to? The objects below only have constants. Can you leave some breadcrumbs in the doc so future readers know what this is referring to?

[goderbauer]

Document: What is a pool in this context? (I don't think we've used that term before in record_use?)

[goderbauer]

Document this. What does the int represent?

[goderbauer]

Upon first reading through this PR I was confused that nothing appears to ever be added to this context. That made me wonder: Is there ever a reason to construct a DeserializationContext with a non-empty constants list? If not, maybe DeserializationContext.constants should just be internally initialized to an empty lists to remove the constructor argument and this code should be refactored to do context.constants.add to make it explicit that we are adding to the context.

[dcharkes]

Hm, maybe I should have folded the follow up PR into this. There I add a comment about this.

The interesting thing is that the serialization is able to do it without mutation because we create the mapping from semantic objects to indices, and then use those indices for the syntax objects. So that can go in one batch. And I tried to keep the contexts mirroring each other for serialization and deserialization. So it feels kind of off to initialize with a mutable list for one but not for the other.

We might want to change this code again, because currently the order is non-determenistic:

• [record_use] Implementation: JSON: Sort the file #3115