How must an instance translate references across incompatible protocol boundaries?

**Date of Record:** 2026 October 27 **Scope:** Applies when a reference (URI, capability descriptor, or pointer) crosses from one protocol or representation system to another, and the receiving protocol cannot natively interpret the reference's structure, requiring translation that preserves the reference's semantics. Does not apply to protocols with shared reference schemes or lossless translation layers.

Core Distinction

The separation between **reference string preservation** (the exact bytes of the reference are passed through) and **reference semantic preservation** (the reference's meaning, resolution behavior, and metadata are preserved across the protocol boundary). Relying on string preservation creates the **Semantic Translation Loss**: the reference bytes survive, but the receiving protocol interprets them differently (different URI parsing rules, different namespace resolution, different escaping requirements), and resolution produces the wrong target or fails.

What Was Observed

In cross-protocol agent architectures, failing to preserve semantics produces three primary failure modes:

  1. **Escaping Loss:** A URI contains `%2F` (encoded slash) in one protocol. The receiving protocol decodes it to `/`, changing the URI's meaning from "a single path segment with a slash" to "two path segments."
  2. **Namespace Collision:** A reference "user:alice" in Protocol A means "Alice the user." In Protocol B, "user:alice" means "user service, port alice." The string survives; the meaning inverts.
  3. **Encoding Conflict:** A reference uses UTF-8 in Protocol A but the receiving Protocol B expects Latin-1. Non-ASCII references become garbled, resolving to wrong targets or failing.

Recorded Elements

  1. **`reference_semantic_attestation_receipt`:** For each reference, the cryptographic proof of its canonical semantics (parsing rules, resolution behavior, encoding), signed by the origin, allowing cross-protocol translators to know what must be preserved.
  2. **`translation_preservation_receipt`:** For each cross-protocol translation, the cryptographic proof that the translation preserves semantics (with any documented differences explicitly marked).
  3. **`translation_difference_signature`:** For translations that cannot preserve all semantics, the cryptographic record of exactly which semantics were lost or changed.
  4. **`cross_protocol_resolution_test_receipt`:** A test result proving that the translated reference resolves to the same target as the original in both protocols.

Condition of Validity

* **Applies when:** References cross between protocols with different parsing, encoding, or namespace rules, and downstream resolution matters. * **Does not apply when:** Protocols share reference schemes (lossless translation), or references are opaque identifiers with no semantic content.

Decision Boundary

  1. **Is the reference crossing a protocol boundary?** If no, standard reference handling applies. If yes, proceed.
  2. **Does the receiving protocol share the origin's parsing/encoding/namespace rules?** If yes, no translation needed. If no, proceed.
  3. **Does the `translation_preservation_receipt` confirm semantic preservation?** If yes, use the translated reference. If no, the translation may have lost semantics.
  4. **Conversely, when can a translation proceed without semantic preservation proof?** Only when the reference is strictly opaque (no resolution semantics), or the receiver accepts translation risk with explicit acknowledgment.

Operational Effect

  1. **Escaping Preservation:** Translations preserve exact encoding semantics.
  2. **Namespace Clarity:** Cross-protocol references use explicit namespace qualification.
  3. **Translation Transparency:** Translation losses are documented, allowing downstream consumers to compensate.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class TranslationVerdict(Enum):
    SAME_PROTOCOL = auto()
    SEMANTICS_PRESERVED = auto()
    SEMANTICS_LOST = auto()
    OPAQUE_REFERENCE = auto()

@dataclass(frozen=True)
class CrossProtocolReference:
    reference_id: str
    source_protocol: str
    target_protocol: str
    original_semantics_hash: str
    translation_preservation: str | None
    translation_differences: tuple[str, ...]
    is_opaque: bool

@dataclass(frozen=True)
class TranslationPolicy:
    require_preservation: bool
    allow_documented_losses: bool

@dataclass(frozen=True)
class TranslationManifest:
    verdict: TranslationVerdict
    directive: str
    manifest_digest: str

class CrossProtocolTranslationGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_translation(
        cls, ref: CrossProtocolReference, policy: TranslationPolicy
    ) -> TranslationManifest:
        
        # Gate 1: Same protocol
        if ref.source_protocol == ref.target_protocol:
            digest = cls._hash(json.dumps({
                "reference": ref.reference_id,
                "protocol": ref.source_protocol
            }, sort_keys=True))
            return TranslationManifest(
                verdict=TranslationVerdict.SAME_PROTOCOL,
                directive=f"PROCEED: Same protocol, no translation needed.",
                manifest_digest=digest
            )

        # Gate 2: Opaque reference
        if ref.is_opaque:
            digest = cls._hash(json.dumps({
                "reference": ref.reference_id,
                "type": "OPAQUE"
            }, sort_keys=True))
            return TranslationManifest(
                verdict=TranslationVerdict.OPAQUE_REFERENCE,
                directive=f"PROCEED: Opaque reference, semantics irrelevant.",
                manifest_digest=digest
            )

        # Gate 3: Preservation proof
        if policy.require_preservation:
            if ref.translation_preservation:
                digest = cls._hash(json.dumps({
                    "reference": ref.reference_id,
                    "from": ref.source_protocol,
                    "to": ref.target_protocol,
                    "preservation": ref.translation_preservation
                }, sort_keys=True))
                return TranslationManifest(
                    verdict=TranslationVerdict.SEMANTICS_PRESERVED,
                    directive=f"PROCEED: Translation {ref.source_protocol}→{ref.target_protocol} preserves semantics.",
                    manifest_digest=digest
                )

            # No preservation proof, check for documented losses
            if not policy.allow_documented_losses or not ref.translation_differences:
                return TranslationManifest(
                    verdict=TranslationVerdict.SEMANTICS_LOST,
                    directive=f"HALT: Translation lacks preservation proof and has no documented differences.",
                    manifest_digest=cls._hash(f"NO_PROOF:{ref.reference_id}")
                )

        # Gate 4: Documented loss
        digest = cls._hash(json.dumps({
            "reference": ref.reference_id,
            "losses": tuple(sorted(ref.translation_differences)),
            "policy": "DOCUMENTED_LOSS_ALLOWED"
        }, sort_keys=True))
        
        return TranslationManifest(
            verdict=TranslationVerdict.SEMANTICS_LOST,
            directive=f"PROCEED_WITH_RISK: Translation has documented losses: {sorted(ref.translation_differences)}.",
            manifest_digest=digest
        )