Which silent API deprecations encountered during execution must be permanently logged?

**Date of Record:** 2026 October 25 **Scope:** Applies when an agentic session dispatches requests to an external API and receives a successful HTTP status (e.g., 2xx) whose payload shape, type, or default behavior deviates from the documented or previously established contract. Does not apply to explicit versioning errors (HTTP 404, 410) or documented, expected environment-specific variations.

Core Distinction

The separation between **transient operational errors** (HTTP 500s, timeouts, or rate limits that correctly indicate failure) and **silent API deprecations** (successful HTTP 200 responses that omit a field, return a mutated default, or change a data type without an explicit version bump). Transient errors trigger standard retry logic. Silent deprecations trigger a false assumption of safety: the instance processes an incomplete payload, makes decisions based on missing data, and reports success. Permanently logging silent deprecations is the only way to prevent successor instances from inheriting the same corrupted assumptions.

What Was Observed

In distributed agent architectures relying on external APIs, failing to permanently log silent deprecations produces three primary failure modes:

  1. **Phantom Data Loss:** An API silently changes its default pagination size from 50 to 10. The instance processes only 10 records, assumes it has reached the end of the dataset, and reports a successful task completion with 80% missing data.
  2. **Type Collapse:** An API changes a field from a stringified integer (`"123"`) to a native integer (`123`), or from a populated list to `null`. The instance's schema validator skips the field or coerces it into `None`, causing downstream deterministic failures in a successor session that expects the old type.
  3. **Error-Masking:** An API that previously returned HTTP 400 for invalid inputs now returns HTTP 200 with a JSON body containing an `"error"` key. The instance logs the call as a success, persists corrupted state, and does not trigger its fail-closed error handling.

Recorded Elements

  1. **`deprecated_field_signature`:** The exact JSON path, header name, or endpoint URI that exhibited the deviation.
  2. **`observed_vs_expected_behavior`:** The deterministic diff between the expected schema (type, default value, presence) and the actual response (e.g., `expected: list[str], observed: null`).
  3. **`api_contract_version`:** The specific API version or schema hash the instance was targeting when the drift was detected.
  4. **`mitigation_predicate`:** The fail-closed logic gate the successor must apply to handle the drift (e.g., "IF `status` is null, THEN re-probe with `?include_status=true`").

Condition of Validity

* **Applies when:** The instance receives an HTTP 2xx response whose structure or default values deviate from the established contract, and the instance lacks an explicit schema version negotiation mechanism that guarantees the old behavior. * **Does not apply when:** The deviation is a documented, expected fallback (e.g., localized currency formatting), or the API client has already enforced strict schema validation that halts execution on type mismatch.

Decision Boundary

  1. **Did the API return a 2xx success status?** If no, apply standard error handling and retry logic. If yes, proceed to schema verification.
  2. **Does the payload strictly match the previously established schema, types, and defaults?** If yes, persist the result normally. If no, proceed to isolate the drift.
  3. **Is the drift an intentional, documented version upgrade?** If yes, update the `api_contract_version` and re-seal the memory. If no, it is a silent deprecation and must be logged as a permanent operational invariant.
  4. **Conversely, when should the instance discard the response rather than log the drift?** If the drift indicates a catastrophic malformed payload (e.g., HTML error page returned with a 200 status), treat it as an execution failure and abort, rather than trying to adapt to the malformed state.

Operational Effect

  1. **Prevents Silent Hallucination:** Ensures that instances do not confidently act on incomplete or null data caused by unannounced API changes.
  2. **Schema Immunity:** Allows successor instances to bypass the discovery phase for known silent deprecations, applying the `mitigation_predicate` immediately upon detecting the mutated field.
  3. **Deterministic Failure:** Converts a silent data corruption into an explicit, loud boundary violation that forces the agent to re-evaluate its assumptions or escalate to a human operator.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json


class SchemaExpectation(Enum):
    TYPE_MATCH = auto()
    DEFAULT_VALUE = auto()
    PRESENCE = auto()


@dataclass(frozen=True)
class ExpectedContract:
    field_path: str
    expected_type: str
    expected_default: str | None = None


@dataclass(frozen=True)
class ObservedResponse:
    field_path: str
    observed_type: str
    observed_value: str | None = None


@dataclass(frozen=True)
class SilentDeprecationRecord:
    field_path: str
    expected: str
    observed: str
    mitigation_predicate: str
    deprecation_digest: str


class ApiDeprecationLogger:
    """
    Compares expected API contracts against observed responses to detect and
    permanently log silent deprecations for successor instances.
    """

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

    @classmethod
    def detect_drift(
        cls,
        expected: tuple[ExpectedContract, ...],
        observed: tuple[ObservedResponse, ...],
    ) -> tuple[SilentDeprecationRecord, ...]:
        
        observed_map = {o.field_path: o for o in observed}
        deprecations: list[SilentDeprecationRecord] = []

        for exp in expected:
            obs = observed_map.get(exp.field_path)

            # Gate 1: Missing field detection
            if obs is None:
                deprecations.append(
                    SilentDeprecationRecord(
                        field_path=exp.field_path,
                        expected=f"PRESENT ({exp.expected_type})",
                        observed="MISSING",
                        mitigation_predicate=f"IF {exp.field_path} is missing, THEN assume default '{exp.expected_default}' or re-probe.",
                        deprecation_digest=cls._hash(f"MISSING:{exp.field_path}"),
                    )
                )
                continue

            # Gate 2: Type collapse detection
            if obs.observed_type != exp.expected_type:
                deprecations.append(
                    SilentDeprecationRecord(
                        field_path=exp.field_path,
                        expected=exp.expected_type,
                        observed=obs.observed_type,
                        mitigation_predicate=f"IF {exp.field_path} is {obs.observed_type}, THEN parse using {obs.observed_type} coercion.",
                        deprecation_digest=cls._hash(f"TYPE:{exp.field_path}:{obs.observed_type}"),
                    )
                )

            # Gate 3: Default value mutation (if explicitly tracked)
            elif exp.expected_default is not None and obs.observed_value != exp.expected_default:
                # Note: This assumes the observed value was accessed when the default was expected
                deprecations.append(
                    SilentDeprecationRecord(
                        field_path=exp.field_path,
                        expected=f"DEFAULT: {exp.expected_default}",
                        observed=f"VALUE: {obs.observed_value}",
                        mitigation_predicate=f"IF {exp.field_path} differs from {exp.expected_default}, THEN recalculate dependent logic.",
                        deprecation_digest=cls._hash(f"DEFAULT:{exp.field_path}:{obs.observed_value}"),
                    )
                )

        return tuple(deprecations)