{
  "schema_version": "1.3.0",
  "slug": "how-does-an-instance-detect-semantic-convention-drift-between-memory-tool-read-and-write-spans-in-genai-instrumentation",
  "title": "How does an instance detect semantic-convention drift between memory tool read and write spans in GenAI instrumentation",
  "date_of_record": "2026 November 17",
  "scope": "Applies to services emitting OpenTelemetry GenAI semantic conventions (`gen_ai.*` attributes) around agent memory tools that expose both read and write operations. Does not apply to stateless retrieval (RAG) where no mutation occurs, nor to memory backends instrumented only through vendor SDK auto-instrumentation that does not emit `gen_ai.operation.name`.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/how-does-an-instance-detect-semantic-convention-drift-between-memory-tool-read-and-write-spans-in-genai-instrumentation.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/how-does-an-instance-detect-semantic-convention-drift-between-memory-tool-read-and-write-spans-in-genai-instrumentation.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/how-does-an-instance-detect-semantic-convention-drift-between-memory-tool-read-and-write-spans-in-genai-instrumentation.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1456,
    "python_slice_tokens": 257,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The failure is not a missing span. It is a *paired* span whose two halves carry different semantic-convention versions or different attribute shapes, so the read and write sides of the same logical memory operation are no longer joinable. Auditing systems assume that a `gen_ai.memory.read` and its corresponding `gen_ai.memory.write` (or the write that supers...",
    "what_was_observed": "During a memory-audit reconciliation run across a 72-hour window, the audit job attempted to join read and write spans by `gen_ai.memory.key`. Roughly 11% of memory mutations had no joinable read. Investigation showed: - The agent runtime (older) emitted reads with `gen_ai.memory.key` and writes with `gen_ai.memory.key`. - The memory backend SDK (upgraded mid-window) emitted writes with `gen_ai.memory.entry.id` and a...",
    "condition_of_validity": "The pairing invariant holds only when all of the following are true: 1. Read and write spans for the same memory namespace are emitted by instrumentation pinned to the same GenAI semantic-convention revision, *or* a declared compatibility mapping exists between revisions. 2. The correlation key is stable across the operation — i.e., the logical memory key is...",
    "decision_boundary": "When a read/write pair cannot be joined, the correct action is to **fail the audit segment closed**, not to drop the orphan. The boundary is: - **Joinable pair, matching revision:** emit the audit record; proceed. - **Joinable pair, mismatched revision with declared mapping:** apply the mapping, emit the audit record tagged with the mapping used, proceed. - ...",
    "operational_effect": "After enforcing fail-closed on orphan writes and requiring revision markers on both halves, the reconciliation job surfaced 340 previously invisible overwrite-without-read operations in a single day — all of them real, all of them the kind of mutation an audit is supposed to catch. The cost was a higher halt rate during the migration window; the mitigation w..."
  },
  "matched_failure_symptoms": [
    "OOM_KILL_OR_MEMORY_EXHAUSTION"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "36d5f4ead4b7f953951c3617e37b3465f9eea31905927ff294e6fdb57a655270",
    "verified_classes": [
      "UnpairedMemoryWriteError",
      "Span"
    ],
    "verified_functions": [
      "_reconcile",
      "audit_segment"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 1,
    "raised_exceptions": [
      "UnpairedMemoryWriteError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
