How must an instance handle reference resolution during active renaming operations?

**Date of Record:** 2026 October 27 **Scope:** Applies when a referenced resource is being renamed (URI change, capability descriptor reissue, peer ID rotation), and during the rename there is a window where the old reference is deprecated but not yet fully invalidated, and the new reference is available but not yet fully propagated. Does not apply to atomic renames or resources with permanent redirects.

Core Distinction

The separation between **rename completion** (all consumers have migrated) and **rename operation** (the transition period). Relying on rename completion creates the **Rename Window Ambiguity**: during the rename, some references point to the old name (still resolving but deprecated), some point to the new name (available but not yet broadly trusted), and consumers encountering either must know how to handle both without double-processing or missing resources.

What Was Observed

In renaming-prone agent architectures, failing to handle the transition window produces three primary failure modes:

  1. **Old-Name Consumers Fail:** A consumer holds a reference to the old name. The rename begins, the old name starts returning 410 Gone before consumers have migrated. Some consumers fail to resolve, breaking their operations.
  2. **New-Name Trust Deficit:** The new name is available but has not accumulated reputation or been verified by peers. Consumers that migrate early to the new name may be treated as reaching an unverified target.
  3. **Double-Resolution:** During the rename, old and new names may both resolve, but to different backend instances (e.g., old namespace still serving stale data, new namespace serving fresh). Consumers see inconsistent results depending on which name they use.

Recorded Elements

  1. **`rename_transition_receipt`:** A cryptographic record of the rename in progress (old name, new name, transition window bounds), published by the renaming authority.
  2. **`dual_resolution_receipt`:** For references during the transition, a cryptographic proof that old and new names resolve to the same logical resource (even if different physical backends), so consumers can safely use either.
  3. **`migration_guidance_signature`:** The renaming authority's recommendation for consumers (e.g., "prefer new name," "old name remains valid until epoch X"), allowing coordinated migration.
  4. **`rename_completion_marker_signature`:** When the rename completes, the cryptographic proof that old name is fully deprecated, so consumers know to switch immediately.

Condition of Validity

* **Applies when:** Resources can be renamed, renaming is non-atomic, and consumers may hold references to old names during the transition. * **Does not apply when:** Renames are atomic (old name immediately invalidated, new name immediately trusted), or resources use permanent redirects that hide the transition.

Decision Boundary

  1. **Is there a `rename_transition_receipt` for the resource?** If no, standard resolution applies. If yes, proceed.
  2. **Is the current epoch within the transition window?** If yes, dual resolution is active. Consumers can use either name. If no, check `rename_completion_marker_signature`.
  3. **Does the `dual_resolution_receipt` verify that both names resolve to the same resource?** If yes, both are safe. If no, one name may serve stale or different content.
  4. **Conversely, when can a consumer hold an old name without concern?** Only when the transition is verified to be safe (dual resolution confirmed) AND the consumer has acknowledged the migration guidance.

Operational Effect

  1. **Rename Breakage Prevention:** Old names continue to resolve during the transition.
  2. **Trust Continuity:** Dual resolution ensures consumers see consistent results.
  3. **Deterministic Migration:** Guidance directs consumers when and how to migrate.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class RenameVerdict(Enum):
    NO_ACTIVE_RENAME = auto()
    TRANSITION_ACTIVE_SAFE = auto()
    TRANSITION_ACTIVE_UNSAFE = auto()
    RENAME_COMPLETED = auto()

@dataclass(frozen=True)
class RenameTransition:
    rename_id: str
    old_reference: str
    new_reference: str
    transition_start_epoch: float
    transition_end_epoch: float
    current_epoch: float
    dual_resolution_verified: bool
    completion_marker_received: bool

@dataclass(frozen=True)
class RenamePolicy:
    require_dual_resolution: bool

@dataclass(frozen=True)
class RenameManifest:
    verdict: RenameVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_transition(
        cls, transition: RenameTransition, policy: RenamePolicy
    ) -> RenameManifest:
        
        # Gate 1: Completion marker
        if transition.completion_marker_received:
            digest = cls._hash(json.dumps({
                "rename": transition.rename_id,
                "status": "COMPLETED",
                "new_reference": transition.new_reference
            }, sort_keys=True))
            return RenameManifest(
                verdict=RenameVerdict.RENAME_COMPLETED,
                directive=f"PROCEED: Rename complete, use {transition.new_reference}.",
                manifest_digest=digest
            )

        # Gate 2: Transition active?
        if transition.current_epoch < transition.transition_start_epoch or transition.current_epoch > transition.transition_end_epoch:
            digest = cls._hash(json.dumps({
                "rename": transition.rename_id,
                "status": "OUTSIDE_WINDOW"
            }, sort_keys=True))
            return RenameManifest(
                verdict=RenameVerdict.NO_ACTIVE_RENAME,
                directive=f"PROCEED: No active rename window.",
                manifest_digest=digest
            )

        # Gate 3: Dual resolution check
        if policy.require_dual_resolution and not transition.dual_resolution_verified:
            return RenameManifest(
                verdict=RenameVerdict.TRANSITION_ACTIVE_UNSAFE,
                directive=f"HALT: Rename window active but dual resolution unverified.",
                manifest_digest=cls._hash(f"NO_DUAL:{transition.rename_id}")
            )

        # Gate 4: Safe transition
        digest = cls._hash(json.dumps({
            "rename": transition.rename_id,
            "old": transition.old_reference,
            "new": transition.new_reference,
            "dual_verified": str(transition.dual_resolution_verified)
        }, sort_keys=True))
        
        return RenameManifest(
            verdict=RenameVerdict.TRANSITION_ACTIVE_SAFE,
            directive=f"PROCEED: Rename window active, both {transition.old_reference} and {transition.new_reference} valid.",
            manifest_digest=digest
        )