Repository navigation
Reuse existing external keys for as-key references - #74
Merged
Merged
Conversation
Prefer a target's existing external key when Reference receives neither an explicit key nor a key type. Generated scalar and list as-key assignments then serialize @ref:external without adding an unnecessary internal key. Retain internal-key reuse and allocation and the explicit INTERNAL override. Add regression coverage for plain targets, COW proxies and reference lists. Include both generated-function reproduction tests from the issue in the permanent test suite. Document the identity, key-selection and ownership principles, distinguishing current behavior from follow-up enforcement. Internal-key allocation is intentional identity bookkeeping: an additional key identifies the existing target without changing its ordinary data. Fixes #73
dschwartznyc
approved these changes
Nov 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When a generated function applies
as-keyto an object with{"@key:external": "p1"},Reference(target)currently selects an internal key, creating one if needed. The output contains{"@ref": "<uuid>"}and an externally keyed input unnecessarily gains an internal key.Prefer the existing external key so the same assignment writes
{"@ref:external": "p1"}without adding a key. This applies to scalar and list references, including targets reached through COW proxies.Closes #73.
Key selection
key_type=KeyType.INTERNALselection.Resolution of the keyless case
We do not adopt the no-key-creation behavior suggested in #73. Every object has an identity, and multiple keys can identify that same object. Allocating an additional key records another representation of its existing identity; it does not create a new object identity or change its ordinary data. Since
as-keyexplicitly requests the target's identity, allocating an internal key when no external or internal key exists is intentional behavior.The target's key metadata and registry may therefore gain an internal key. This is identity bookkeeping, rather than an ordinary data write requiring a COW copy. The key remains associated with the existing target. Java's different key-allocation behavior does not establish a defect in this Python contract.
These principles and the ownership rule are documented in Object identity and references. The document distinguishes implemented key selection from the agreed access rule requiring follow-up enforcement.
The defect in #73 is the unnecessary allocation or selection of an internal key when a usable external key already exists. This change fixes that defect, and both supplied reproduction tests pass. The keyless case is resolved by retaining automatic internal-key allocation under the identity principles above.
Protection against ordinary data writes through references into the caller's graph is separate follow-up work. The agreed rule for that work is that these references grant read access and identity access, while data writes require ownership.
Validation
as-keyignores the object's existing key and changes the function's input #73 as permanent tests intest/test_keys_and_references.py. Coverage includes external-only and dual-key targets, internal-key reuse, explicit internal selection, scalar/list serialization and COW wrappers.as-keyignores the object's existing key and changes the function's input #73.test/test_cached_json_rune_object_deserializer.py::test_init_invalid_directory_or_module, also reproduced before the change.git diff --checkpassed.