ai-editor-tree-engine 1.0.147__py3-none-any.whl

ai_editor_tree_engine-1.0.147.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: ai-editor-tree-engine
+Version: 1.0.147
+Summary: Format-independent parse/tree/identity/render engine used as the ai-editor server's internals
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: lark<2.0,>=1.3.1
+Provides-Extra: tree-engine-python
+Requires-Dist: libcst<2.0,>=1.8.6; extra == "tree-engine-python"
+Provides-Extra: tree-engine-bsl
+Requires-Dist: tree-sitter<0.26,>=0.25; extra == "tree-engine-bsl"
+Requires-Dist: tree-sitter-bsl<0.2,>=0.1.6; extra == "tree-engine-bsl"
+Provides-Extra: tree-engine
+Requires-Dist: libcst<2.0,>=1.8.6; extra == "tree-engine"
+Requires-Dist: tree-sitter<0.26,>=0.25; extra == "tree-engine"
+Requires-Dist: tree-sitter-bsl<0.2,>=0.1.6; extra == "tree-engine"
+Dynamic: license-file

ai_editor_tree_engine-1.0.147.dist-info/RECORD

@@ -0,0 +1,72 @@
+ai_editor_tree_engine-1.0.147.dist-info/licenses/LICENSE,sha256=6KdtUcTwmTRbJrAmYjVn7e6S-V42ubeDJ-AiVEzZ510,1075
+tree_engine/errors.py,sha256=m07NG827Xtso7165eF9nTxV9ignaZ5aJfvqvV2Jm0sQ,3881
+tree_engine/exceptions.py,sha256=mHoPsrQfM_RY_QDkt1lFtgPy87bpT7BQizNn-Wmqv1E,10640
+tree_engine/facade.py,sha256=CYf43_bRPKd98E9C0HNT1vWzojXX7fRKSdOrgJ1o4-8,133214
+tree_engine/core/address.py,sha256=aGeiIZAVtVCjpgPdOY7pE9-jkbQNUWH1DsddSHFSO_E,14741
+tree_engine/core/identifier_map.py,sha256=OXK_2r8ZZ3nohJqUfwNwntJjjHmxMdC6ZPscjpOfw_I,11681
+tree_engine/core/identity.py,sha256=BcUMWoPpvBC-8h81G_RQkCd3Wy8ymFI91U0ppk0ZC4A,8157
+tree_engine/core/instrumentation.py,sha256=p_4jwEtgWH25f59N6xKND2VdNGGAT3VqcD6h473Z8e8,17121
+tree_engine/core/integrity.py,sha256=sXl-SyfsUo7XiJG1lU45J3NK3hD2exHBy2s0WMLzAAo,14560
+tree_engine/core/integrity_full.py,sha256=dyoMc2vvTMcU5grGBWy8z7Zf6fpXexhuviI0paSpeQk,16272
+tree_engine/core/journal.py,sha256=xjA7WlWdOEqKsMSi4bvwJMvkGpzH2NJ_HYP-M8vGDz8,9705
+tree_engine/core/journal_compose.py,sha256=wVmtRbaEj3LWiaZMezPrzfjhEJHkUr_Bt1K8nPDoJ_k,21766
+tree_engine/core/live_tree.py,sha256=uN8FcvwOgJ-gxZQshs9wJv62vUnPa8RMtnJg0RiMNS8,32306
+tree_engine/core/locking.py,sha256=bsVilRJB-rGhnb0lI3TGyjIkrLt93ZVNQBPp1l2nm9Y,8754
+tree_engine/core/move.py,sha256=6gx9lWm9_xSyXmsSEFJVr_flvZRGJj0hGB-EHxIQQ9s,26378
+tree_engine/core/move_references.py,sha256=mTLbrHIiV8tIm_mtAD52wDvozTsuegVyJMLRihNS-PI,13971
+tree_engine/core/node_types.py,sha256=n8aZ-kQ-rbZbQhxV1_kTnevTU5SRnsPZZHbWTZp3344,17464
+tree_engine/core/nodes.py,sha256=jvRt8T19Ba6yNqXWjaAUmVoZqUrRqPg7JosaQ09h38Y,14787
+tree_engine/core/operations.py,sha256=_mOzRz5LIGWIR8a5BhT2C07Tus31lmRwakrAAUD6fE8,32461
+tree_engine/core/plugin_boundary.py,sha256=KHseccyHmcHaPxpBykbmedzNU07nQ4MQg3z03fPAmb8,7196
+tree_engine/core/position_map.py,sha256=JJM3cPM0KZG_oom2423nDCLKCtfJ2NKhqjHiSnIJX-o,9695
+tree_engine/core/reference_cache.py,sha256=EdxaOiICUIc60jme1SVBhqC6zOi5TCbqOKcze_2cXVY,15023
+tree_engine/core/references.py,sha256=61X6-3yX_qEtzXKAP0Galpw0co6gF77rOelfeGrTNKg,9907
+tree_engine/core/reparse.py,sha256=kF_-qjJun53Ve1pBVZkX8nXxkxmSo7LB1JsiQkoRU_o,16898
+tree_engine/core/short_id.py,sha256=3OrJRWQsnsqiQRvUEaNoiKchYKlZ0FwKWvPkhl9MGgU,11361
+tree_engine/core/subtree_apply.py,sha256=D7cPUllR9bVEbXFLtiXOIe3-nDHQnXeVgnvC0B0r1v4,16244
+tree_engine/core/subtree_copy.py,sha256=YsnW0jFYeyNlbJSJp_PyAcWZX8L54yTHuWoX3qubRAI,15967
+tree_engine/core/transactions.py,sha256=krlPKMWUxp7wr2VARxQRz3Izo79xXy2zJ4_A-S15XxU,19006
+tree_engine/core/trivia.py,sha256=qyd37VIJOdqn73lsD3Dm81t5QoavrgxOMz5Tp4NOqSE,16728
+tree_engine/core/updates.py,sha256=41V9WvnAY9R9tE44DmZUpeC1V26T6OhCNTZnXN3fFts,18591
+tree_engine/core/validation.py,sha256=ijHSIvhG3RVg3mm7jVsFU1Wkery-ucUD_cE7gvqi5ng,16249
+tree_engine/plugins/contract.py,sha256=s_RTp4K6OdJX9rUfvQMZPQGC4U8YXf9FqqPnbBpHOQc,14292
+tree_engine/plugins/detachable.py,sha256=3K9OMWqLY-7v55mOUuFrdCuJvXOXe9CuEpSvqxCuRFM,7064
+tree_engine/plugins/fallback.py,sha256=9IS83CBANCQ5dtftS4-q97dzBcqEtAWDkDHNnXlUB8I,18044
+tree_engine/plugins/ini_format.py,sha256=KlQhFm5YkrbMbb8YR_sRv-KSfdyMdMGqNtrpZu5Our8,11484
+tree_engine/plugins/json_format.py,sha256=J-QzLdNQAZRLfLbeZ1ME-H6BxZq4eBcHB_yVUU-NBZc,40026
+tree_engine/plugins/json_pointer.py,sha256=oXHcab0_BT2cDtJwmIrEvPa6CUoSFx-0vR3lTDggQBw,8185
+tree_engine/plugins/plain_text.py,sha256=drGE9HCk12gq5hbiXGo1zgAUa0S8v0HerRDnNfyKN6o,55326
+tree_engine/plugins/registry.py,sha256=o31HKHCAjuH7AwkL98i7LM9gi6ay0idqZwsF5Qj2VW4,17053
+tree_engine/plugins/selection.py,sha256=aHNjt2jcDLc6cuCABfgNn3yFoTvY2tEmLqzeesVhNSY,9692
+tree_engine/plugins/toml_format.py,sha256=JmSBv9yBTL8LGEaIRcB-gDnlLbaYZSgCEd0JlTdhrV0,26505
+tree_engine/plugins/bsl/dialects.py,sha256=sv5nJdb2DVyZisqmh-CgVHQ9I6AHG1oy-VxxVjxgGa4,11856
+tree_engine/plugins/bsl/generator.py,sha256=_PSAPmqyWDXK7jB9Lo6c9xmBJtc02ELa_KKFhfw3nmE,17821
+tree_engine/plugins/bsl/import_map.py,sha256=us00evFEIrhOANusfxJ409TJ48CkMG9BQkkXnlnSXlc,16864
+tree_engine/plugins/bsl/plugin.py,sha256=YJzR00TsMqcj2eOts2TfYaA7VnIMf9_8wImPI4Z28J0,16563
+tree_engine/plugins/python/export_map.py,sha256=ZM0IWskuUogSgJLspmlLEH03577cWBaawXR0k7yQa2Q,14089
+tree_engine/plugins/python/import_map.py,sha256=QEa4xJuoMjobN1wvcGot_pahI2dJTWxDf4Kpk56f8BM,18196
+tree_engine/plugins/python/plugin.py,sha256=rYqgsGGFa8J1O8L7cR2FHxWqn4x-7B05GINM_2zW0Co,35589
+tree_engine/plugins/yaml/builder.py,sha256=xbCU0fAGJeL38D9BWv-K8ihlThZPLxhWw9mPMGg6F9E,1972
+tree_engine/plugins/yaml/emitter.py,sha256=bVBS-rZ7gEXjVEp6TQEs5S6iBxH3Tiirbf6-Wm2WsGo,8436
+tree_engine/plugins/yaml/flow.py,sha256=BR4kdj02twSdX36mCbxRgWVPehivwOxZvdvEtn6M7wc,8627
+tree_engine/plugins/yaml/plugin.py,sha256=vwwpKAluKbD_-I_ICOS--RzCXKAodlfPuPoRv1jEoVk,15037
+tree_engine/plugins/yaml/reader.py,sha256=-GvuFgOx-SV5hl2WLe_kWaub2SZlY1ZPY_GmbFJ6TkI,16994
+tree_engine/plugins/yaml/scanner.py,sha256=Cp77W_o-_0kgkE5XoBNvbgbtIb_u_Gy4wCzcWSuyrrc,12068
+tree_engine/query/adapter.py,sha256=ba7Mp8pb6kqNgYE6ZoJNLcRpWnbS9fnd6TRw3u2uO4Y,12076
+tree_engine/query/engine.py,sha256=9bxKSrAkygaXjaPyQly9WziDR-D8oYvy22UqL-FFINo,19827
+tree_engine/query/inspection.py,sha256=6BiEe0XhDowfyjLsMBdKnPQCnLEbs0ahoE8R6h7td9c,23940
+tree_engine/query/outline.py,sha256=aWcPP3Oz0CtJfk3ywBDVibD-POGNpcmkgbSiTILAfp4,12116
+tree_engine/query/predicates.py,sha256=uWhsbUBI7EY5C_1-rLik0op4MKHgUGZ52VYgFP0Lj0U,9938
+tree_engine/query/results.py,sha256=YhInAYJlrkEWU-JhFeCnfnp-SEEsRyTTEju3A4GoxbI,6267
+tree_engine/query/selector.py,sha256=AqqrHVg1DfbwjXASTzRMCor1zj-2lQkjrN3gMM9afUg,13616
+tree_engine/storage/codec.py,sha256=AAXEw2sdIVeqeexRuUsUFjXL0Ku5QmMsh2mMnN1GLOA,20421
+tree_engine/storage/document_bridge.py,sha256=y5hRQI0ezrX2rDq8wz96wKkX-Yng2pKNFKmeODweIo4,29033
+tree_engine/storage/file_txn.py,sha256=IUatv32ktdjnk0_JEH_-8JtXVlSTqSAbFUcCNbdS-3Y,13442
+tree_engine/storage/history.py,sha256=8ymE2EC1GxWd-yUshFlDKmtt9x5QmzKSUSvp1H-81u4,5373
+tree_engine/storage/lifecycle.py,sha256=mlJ2_nP24LSnAVG7v4yp1WO294iixuaFDxp7Q96Xmm8,32172
+tree_engine/storage/schema.py,sha256=j-y1dcLTRk_YK3loO7fKUe9XwNzhJZwzBeKQ1aVaG2A,16908
+tree_engine/storage/session_guard.py,sha256=Ohj5F5_-KVIGnjIbJpSN2wbGTQMJlZL_3MwPS2IMzVc,17947
+ai_editor_tree_engine-1.0.147.dist-info/METADATA,sha256=Dmeby78BHWp3wQaGnRxk8ErY-LuYXC-etbZ9r9SqnCU,834
+ai_editor_tree_engine-1.0.147.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ai_editor_tree_engine-1.0.147.dist-info/top_level.txt,sha256=cWBMqIrMERXRH2Fh8V7A8SpvVXvZUQLDp2gDSpJlT1A,12
+ai_editor_tree_engine-1.0.147.dist-info/RECORD,,

ai_editor_tree_engine-1.0.147.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ai_editor_tree_engine-1.0.147.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vasiliy Zdanovskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_editor_tree_engine-1.0.147.dist-info/top_level.txt

@@ -0,0 +1 @@
+tree_engine

tree_engine/core/address.py

@@ -0,0 +1,376 @@
+"""Canonical address-normalization layer for concept C-004 (NodeIdentityAndAddressing).
+
+Scope (concept C-004, narrowed to string-form serialization of ``NodeAddress``
+and the mandatory ``normalize_node_address`` entry point): this module owns
+the ``to_str``/``from_str`` external string-form helpers for the imported
+``NodeAddress`` type, the single ``normalize_node_address`` function every
+public node-address operation must call first per {j9rh}, the
+``NodeAddressError`` exception hierarchy, and the {p021} node-view helper
+``build_node_address_view``.
+
+ACCEPTANCE NOTE (orchestrator integration decision): the canonical
+``NodeAddress`` and ``AddressRemap`` types are defined in the sibling module
+``tree_engine.core.identity`` -- this file imports ``NodeAddress`` from
+there and never redefines it. This module is read-only with respect to
+document state: no code path here mutates a short_id map, a node table, a
+generation counter, or an allocator.
+
+Sibling contract not yet available as an importable module in this worktree
+-- the document-local bidirectional short_id<->UUID4 map (``short_id.py``,
+delivered by a parallel T-001 artifact) -- is consumed here only as a
+caller-injected, duck-typed callable, following the same pattern already
+used by ``core/validation.py`` (``next_short_id``) and ``core/node_types.py``
+(``index_map_hook``): this file never imports that sibling module and never
+stubs a fake replacement for it.
+
+``document`` is consumed only through minimal, duck-typed attributes, the
+same convention ``core/identity.py``'s ``replace_node_id`` and
+``core/validation.py``'s ``validate_mutation`` already rely on:
+
+* ``document.nodes_by_id`` -- a mapping (supports ``in``) of canonical
+  ``uuid.UUID`` node_id to node object. Read-only here.
+* ``document.resolve_short_id(short_id: int) -> Sequence[uuid.UUID]`` --
+  the short-id-map module's public accessor, consulted only when no
+  ``resolve_short_id`` callable is explicitly injected into
+  :func:`normalize_node_address`. It returns the sequence of node_id
+  matches for ``short_id`` (normally zero or one; more than one is treated
+  defensively as an ambiguous resolution rather than assumed impossible).
+
+Source-of-truth requirement labels honored here: {j9rh}, {p021}, {p080}.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Sequence, Union
+from uuid import UUID
+
+from tree_engine.core.identity import NodeAddress
+
+__all__ = [
+    "to_str",
+    "serialize",
+    "from_str",
+    "parse",
+    "NodeAddressError",
+    "UnknownAddressError",
+    "AmbiguousAddressError",
+    "ForeignDocumentAddressError",
+    "ShortIdResolver",
+    "normalize_node_address",
+    "NodeAddressView",
+    "build_node_address_view",
+]
+
+# Duck-typed accessor injected by a caller (or looked up on ``document`` as
+# ``document.resolve_short_id``) to resolve a positive-int short_id to the
+# sequence of matching canonical node_id values. See module docstring.
+ShortIdResolver = Callable[[int], Sequence[UUID]]
+
+_HEX_PREFIXES = ("0x", "0X")
+
+
+# --------------------------------------------------------------------------
+# External string-form serialization ({p080} explicit round-trip form)
+# --------------------------------------------------------------------------
+
+
+def to_str(address: NodeAddress) -> str:
+    """Serialize ``address`` to its ``"document_id:node_id"`` string form.
+
+    Both parts are always emitted explicitly as canonical hyphenated UUID4
+    strings, regardless of the implicit-local in-memory form ``NodeAddress``
+    otherwise permits. Raises ``ValueError`` when ``address.document_id`` is
+    ``None`` (the implicit-local form), since no document identifier is
+    then available to emit.
+    """
+
+    if address.document_id is None:
+        raise ValueError(
+            "cannot serialize NodeAddress to its string form: document_id "
+            "is None (implicit-local form carries no explicit document_id)"
+        )
+    return f"{address.document_id}:{address.node_id}"
+
+
+# Alias, per the step spec's "to_str/serialize" naming.
+serialize = to_str
+
+
+def from_str(text: str) -> NodeAddress:
+    """Parse the ``"document_id:node_id"`` string form into a ``NodeAddress``.
+
+    Both parts are required. Raises ``ValueError`` for any malformed input:
+    a non-string argument, a missing or extra ``":"`` separator, an empty
+    segment, or a segment that is not a syntactically valid UUID.
+    """
+
+    if not isinstance(text, str):
+        raise ValueError(f"expected a str, got {type(text).__name__}")
+
+    parts = text.split(":")
+    if len(parts) != 2:
+        raise ValueError(
+            f"malformed node address {text!r}: expected exactly one ':' "
+            f"separator (document_id:node_id), found {len(parts) - 1}"
+        )
+
+    document_part, node_part = parts
+    if not document_part or not node_part:
+        raise ValueError(f"malformed node address {text!r}: empty segment")
+
+    try:
+        document_id = UUID(document_part)
+        node_id = UUID(node_part)
+    except (ValueError, AttributeError, TypeError) as exc:
+        raise ValueError(f"malformed node address {text!r}: invalid UUID segment") from exc
+
+    return NodeAddress(document_id=document_id, node_id=node_id)
+
+
+# Alias, per the step spec's "from_str/parse" naming.
+parse = from_str
+
+
+# --------------------------------------------------------------------------
+# Exception hierarchy
+# --------------------------------------------------------------------------
+
+
+class NodeAddressError(Exception):
+    """Base error for a rejected node-address normalization.
+
+    Always carries the offending raw ``address`` argument exactly as given
+    to :func:`normalize_node_address`, so a caller can inspect what was
+    rejected without re-parsing an error message.
+    """
+
+    def __init__(self, raw_address: Any, message: Optional[str] = None) -> None:
+        self.raw_address = raw_address
+        super().__init__(message or f"invalid node address: {raw_address!r}")
+
+
+class UnknownAddressError(NodeAddressError):
+    """Raised when ``address`` cannot be resolved to any node of the document.
+
+    Covers a UUID4 node_id absent from the document's node table and an
+    int/hex short_id absent from the document's short_id map.
+    """
+
+
+class AmbiguousAddressError(NodeAddressError):
+    """Raised when short_id resolution defensively detects more than one match.
+
+    The short_id<->UUID4 map is a bidirectional map and should never
+    legitimately produce more than one match for a single short_id; this
+    error exists purely as a defensive guard against that invariant being
+    violated, rather than an assumption that it cannot happen.
+    """
+
+
+class ForeignDocumentAddressError(NodeAddressError):
+    """Raised when ``address`` explicitly names a document_id other than the current one.
+
+    Raised immediately, before any local short_id-map or node-table lookup
+    is attempted -- ``document_id`` carries the offending foreign document
+    identifier.
+    """
+
+    def __init__(self, raw_address: Any, document_id: UUID, message: Optional[str] = None) -> None:
+        self.document_id = document_id
+        super().__init__(
+            raw_address,
+            message
+            or (
+                f"node address {raw_address!r} names foreign document_id "
+                f"{document_id!r}"
+            ),
+        )
+
+
+# --------------------------------------------------------------------------
+# normalize_node_address -- the single mandatory entry point per {j9rh}
+# --------------------------------------------------------------------------
+
+
+def _validate_node_id_presence(document: Any, node_id: UUID, raw_address: Any) -> UUID:
+    """Confirm ``node_id`` is present in ``document.nodes_by_id``, or reject.
+
+    Pure lookup: never mutates ``document`` or anything reachable from it.
+    """
+
+    nodes_by_id = getattr(document, "nodes_by_id", None)
+    if nodes_by_id is None or node_id not in nodes_by_id:
+        raise UnknownAddressError(raw_address)
+    return node_id
+
+
+def _resolve_node_address_value(
+    document: Any,
+    node_address: NodeAddress,
+    raw_address: Any,
+    current_document_id: Optional[UUID],
+) -> UUID:
+    """Apply the foreign-document check, then validate the local node_id."""
+
+    if node_address.document_id is not None and node_address.document_id != current_document_id:
+        raise ForeignDocumentAddressError(raw_address, node_address.document_id)
+    return _validate_node_id_presence(document, node_address.node_id, raw_address)
+
+
+def _resolve_short_id(
+    document: Any,
+    short_id: int,
+    raw_address: Any,
+    resolve_short_id: Optional[ShortIdResolver],
+) -> UUID:
+    """Resolve a positive-int short_id via the injected or duck-typed accessor.
+
+    Never touches the short-id-map's internal storage directly: it only
+    calls the public accessor, either explicitly injected by the caller or
+    found as ``document.resolve_short_id``. Read-only: performs no
+    mutation regardless of outcome.
+    """
+
+    resolver = resolve_short_id if resolve_short_id is not None else getattr(
+        document, "resolve_short_id", None
+    )
+    if resolver is None:
+        # No accessor available at all: the address cannot be resolved.
+        raise UnknownAddressError(raw_address)
+
+    matches = list(resolver(short_id))
+    if len(matches) == 0:
+        raise UnknownAddressError(raw_address)
+    if len(matches) > 1:
+        raise AmbiguousAddressError(raw_address)
+    return matches[0]
+
+
+def normalize_node_address(
+    document: Any,
+    address: Union[UUID, int, str, NodeAddress],
+    *,
+    current_document_id: Optional[UUID],
+    resolve_short_id: Optional[ShortIdResolver] = None,
+) -> UUID:
+    """Resolve any accepted address form to its canonical ``uuid.UUID`` node_id.
+
+    The single mandatory entry point every public node-address operation
+    must call first, per {j9rh}. Accepts ``address`` as:
+
+    * ``uuid.UUID`` -- a canonical node_id, validated against
+      ``document.nodes_by_id``.
+    * ``int`` -- a positive document-local short_id, resolved through the
+      short_id map.
+    * ``str`` -- a ``"0x"``-prefixed hex short_id, a DECIMAL-digit short_id,
+      a bare UUID string, or a serialized ``"document_id:node_id"``
+      ``NodeAddress`` (see :func:`from_str`). The decimal form is tried
+      before the UUID form and resolves exactly like the ``int`` it spells,
+      so ``"3"`` and ``3`` are the same address: callers that carry a
+      short_id through a string-typed protocol field -- the editor's
+      ``node_ref`` is one -- would otherwise fall through every branch and
+      be rejected as unknown. Only ASCII digits count, so a non-ASCII
+      decimal digit is not silently reinterpreted.
+    * ``NodeAddress`` -- resolved directly.
+
+    A ``NodeAddress``-shaped address (an explicit ``NodeAddress`` instance
+    or a serialized string form) whose ``document_id`` differs from
+    ``current_document_id`` raises :class:`ForeignDocumentAddressError`
+    immediately, before any local short_id-map or node-table lookup. An
+    unresolvable UUID or short_id raises :class:`UnknownAddressError`. A
+    defensively-detected multi-match short_id resolution raises
+    :class:`AmbiguousAddressError`. Every rejection path is read-only: no
+    mutation of the short_id map, node table, generation counters, or
+    allocator state, and no partial operation is ever started.
+
+    Returns the canonical ``uuid.UUID`` node_id -- the canonicalization
+    target per {j9rh} -- never a ``NodeAddress``.
+    """
+
+    raw_address = address
+
+    if isinstance(address, NodeAddress):
+        return _resolve_node_address_value(document, address, raw_address, current_document_id)
+
+    if isinstance(address, UUID):
+        return _validate_node_id_presence(document, address, raw_address)
+
+    if isinstance(address, bool):
+        # bool is a subclass of int in Python; explicitly not an accepted
+        # address form.
+        raise UnknownAddressError(raw_address)
+
+    if isinstance(address, int):
+        if address <= 0:
+            raise UnknownAddressError(raw_address)
+        return _resolve_short_id(document, address, raw_address, resolve_short_id)
+
+    if isinstance(address, str):
+        if address.startswith(_HEX_PREFIXES):
+            try:
+                short_id = int(address, 16)
+            except ValueError:
+                raise UnknownAddressError(raw_address) from None
+            if short_id <= 0:
+                raise UnknownAddressError(raw_address)
+            return _resolve_short_id(document, short_id, raw_address, resolve_short_id)
+
+        if ":" in address:
+            try:
+                parsed_address = from_str(address)
+            except ValueError:
+                raise UnknownAddressError(raw_address) from None
+            return _resolve_node_address_value(
+                document, parsed_address, raw_address, current_document_id
+            )
+
+        if address.isascii() and address.isdigit():
+            short_id = int(address)
+            if short_id <= 0:
+                raise UnknownAddressError(raw_address)
+            return _resolve_short_id(document, short_id, raw_address, resolve_short_id)
+
+        try:
+            node_id = UUID(address)
+        except ValueError:
+            raise UnknownAddressError(raw_address) from None
+        return _validate_node_id_presence(document, node_id, raw_address)
+
+    raise UnknownAddressError(raw_address)
+
+
+# --------------------------------------------------------------------------
+# View contract per {p021}
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class NodeAddressView:
+    """The pair of identifiers {p021} requires every node view to expose.
+
+    ``short_id_hex`` is the compact, ``"0x"``-prefixed hexadecimal
+    rendering used for later re-addressing; ``node_id`` is the canonical
+    UUID4 string. ``short_id_hex`` never replaces ``node_id`` -- both are
+    always present together.
+    """
+
+    short_id_hex: str
+    node_id: str
+
+
+def build_node_address_view(node_id: Union[UUID, str], short_id: int) -> NodeAddressView:
+    """Build the {p021} view pair from a canonical node_id and its short_id.
+
+    ``node_id`` may be given as a ``uuid.UUID`` or its canonical string
+    form; ``short_id`` is the positive document-local integer id. Every
+    node listing/view assembler elsewhere in the tree engine is expected to
+    call this helper so ``short_id_hex`` and ``node_id`` are always
+    populated together.
+    """
+
+    node_id_value = node_id if isinstance(node_id, UUID) else UUID(str(node_id))
+    return NodeAddressView(
+        short_id_hex=f"0x{int(short_id):x}",
+        node_id=str(node_id_value),
+    )