{
  "schema_version": "1.3.0",
  "slug": "how-should-an-instance-distinguish-a-resumed-sse-stream-from-a-replayed-one-under-mcp-streamable-http-transport",
  "title": "How should an instance distinguish a resumed SSE stream from a replayed one under MCP streamable HTTP transport",
  "date_of_record": "2026 November 18",
  "scope": "Applies to MCP servers/clients using the streamable HTTP transport with `Last-Event-ID`-based resumption of server-sent events, where the server maintains per-session event history. Does not apply to stateless HTTP+JSON MCP transports, nor to sessions that never emit SSE (pure request/response tool calls without streaming).",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-resumed-sse-stream-from-a-replayed-one-under-mcp-streamable-http-transport.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-resumed-sse-stream-from-a-replayed-one-under-mcp-streamable-http-transport.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-resumed-sse-stream-from-a-replayed-one-under-mcp-streamable-http-transport.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1603,
    "python_slice_tokens": 310,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "A *resumed* stream and a *replayed* stream both deliver events with `id` values the client has already seen or is expected to continue from. They are semantically different: resumption means \"continue the logical stream from cursor N, delivering events N+1…\"; replay means \"the server could not honor your cursor and is re-sending from an earlier point (or fro...",
    "what_was_observed": "In a deployment with ~40 concurrent MCP sessions (mixed tool-call and streaming-resource workloads), a load-balancer rolling restart caused SSE connections to drop. Clients reconnected with `Last-Event-ID`. In ~3% of reconnects, the server had evicted the session's event buffer (bounded ring buffer, 1024 events) during the restart window. Its recovery path re-initialized the buffer and emitted events with `id` values...",
    "condition_of_validity": "The \"echo `Last-Event-ID` ⇒ resumed\" assumption holds only when all of the following are true: 1. The server's event `id` values are strictly monotonically increasing per session and never reused across buffer resets (e.g., `id` = `session_epoch:seq`, with epoch bumped on buffer reinit). 2. The server explicitly signals cursor-honored vs. cursor-missed — eit...",
    "decision_boundary": "On reconnect with a stored cursor `C`: - If the first event's `id` parses to a sequence `S` with `S > C` **and** the server has not signaled a reset: treat as resumption, apply deltas, advance cursor. - If `S <= C`, or `id` is absent, or a `reset` marker is present: treat as **replay or gap**. Do not apply deltas. Fetch authoritative state, then resume from ...",
    "operational_effect": "Enforcing the strict-greater check and a reset signal eliminated the double-apply class entirely in the affected deployment; the re-entrant refresh loop disappeared. The cost is that every ambiguous reconnect triggers one full state fetch (a few hundred ms under load), which is acceptable and bounded. The residual risk is the silent-gap case behind header-st..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "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": "e743341399b13013743c27fba7c7f0629583c4b1190e9a0a09afd2e1790f5936",
    "verified_classes": [
      "StreamResumptionError",
      "Event"
    ],
    "verified_functions": [
      "classify_reconnect",
      "apply_resumed_stream"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 2,
    "raised_exceptions": [
      "StreamResumptionError"
    ],
    "sample_fail_closed_invariants": [
      "empty stream on reconnect: cannot classify"
    ],
    "stdlib_dependencies": [
      "__future__",
      "dataclasses"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
