DEV Community

Cover image for FullAgenticStack WhatsApp-first: RFC-WF-0010
suissAI
suissAI

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0010

RFC-WF-0010

Idempotency & Delivery Semantics (IDS)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0001 (WFCS), RFC-WF-0003 (CCP), RFC-WF-0005 (CRCD), RFC-WF-0006 (EAS), RFC-WF-0009 (TMSI)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies Idempotency & Delivery Semantics (IDS) for WhatsApp-first systems. IDS defines normative requirements to ensure exactly-once effects over inherently unreliable delivery conditions (duplicates, retries, reordering) typical of messaging/webhook-driven architectures. IDS standardizes: idempotency key derivation, deduplication storage semantics, outcome replay, confirmation binding, retry windows, and evidence emission for idempotent command execution.

Index Terms— idempotency, at-least-once delivery, deduplication, exactly-once effects, replay safety, distributed systems, webhooks, command execution.

I. Introduction

WhatsApp-first systems rely on conversational ingress and webhook-based delivery. Such systems MUST assume at-least-once delivery at boundaries and MUST therefore implement idempotency to prevent duplicate side effects (double charge, double cancel, repeated refunds). IDS defines a protocol substrate that makes command execution replay-safe and auditable.

IDS complements CCP by formalizing idempotency in a way that is testable, certifiable, and portable across services.

II. Scope

IDS specifies:

  • Delivery assumptions and required semantics at system boundaries
  • Idempotency key derivation rules (normative)
  • Deduplication store behavior, TTL, and collision handling
  • Outcome replay requirements (“same input → same outcome”)
  • Binding of confirmations/tokens to envelopes and idempotency keys
  • Retry behavior and non-idempotent effect shielding
  • Evidence requirements for idempotency decisions

IDS does not prescribe a database technology; it specifies behavioral requirements.

III. Normative Language

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are normative.

IV. Definitions

Delivery Attempt: Any delivery of the same logical message/command due to retries/duplicates.
Exactly-once Effects: The property that side effects occur once even if requests are delivered multiple times.
Dedup Store: Storage that records idempotency keys and outcomes to prevent re-execution.
Outcome Replay: Returning the previously computed outcome for a duplicate idempotency key.
Idempotency Window: The period during which duplicate keys are recognized and replayed.

V. Delivery Assumptions (Normative)

An IDS-compliant system MUST assume:

  • D1: Ingress events may be delivered more than once.
  • D2: Ingress events may be delayed.
  • D3: Ordering is not guaranteed across independent flows.
  • D4: A client may resend the same request intentionally or accidentally.

Therefore, the system MUST provide exactly-once effects for all state-mutating commands.

VI. Idempotency Classes

Commands MUST be classified (and declared in CRCD) into one of:

  • I0 — Read-only: No dedupe required for effects (logging recommended).
  • I1 — Strict Idempotent Mutation: Same logical command MUST produce same effects and same outcome.
  • I2 — Windowed Idempotent Mutation: Same logical command is deduped within a bounded window (e.g., minutes/hours).
  • I3 — External Side-Effect Shielded: Command triggers non-idempotent external calls; requires additional shielding (Section XI).

Default for any mutation MUST be I1 unless explicitly justified and declared.

VII. Normative Idempotency Key Derivation

A. Requirement

Every state-mutating command MUST have an idempotency_key computed from a canonical command envelope (CCP), using stable normalization rules.

B. Minimum Key Inputs

The key MUST include, at minimum, the following normalized fields:

  • tenant_id
  • actor_id (or acting principal)
  • intent.entity
  • intent.action
  • intent.target (stable identifier(s) when applicable)
  • args (normalized)
  • command_kind (mutation class; optional but recommended)

C. Canonicalization Rule

Implementations MUST define deterministic canonicalization (e.g., JSON canonical form with stable key ordering). Canonicalization MUST NOT include ephemeral fields such as timestamps, message ids, or random tokens.

D. Key Function

The key MUST be computed as:

idempotency_key = HASH( CANONICAL( key_inputs ) )

Where HASH SHOULD be SHA-256 (or stronger).

E. Actor Binding Exceptions

If policy allows multiple actors to trigger the same logical mutation (e.g., “system retries” on behalf of user), the model MUST define the binding principal explicitly (e.g., effective_actor_id) and use that in key derivation to avoid accidental double effects.

VIII. Deduplication Store Semantics

A. Atomic Check-and-Set

For any mutating command, the system MUST perform an atomic operation:

  1. Check if idempotency_key exists
  2. If not, reserve it and proceed
  3. If yes, replay outcome (Section IX)

This MUST be atomic to prevent race conditions under concurrent duplicates.

B. Stored Fields (Minimum)

The dedup store MUST record at least:

  • idempotency_key
  • command_id (original)
  • status (in_progress | executed | failed | rejected | compensated)
  • outcome_ref (pointer to EAS artifact(s) or stored outcome blob)
  • created_at, updated_at
  • ttl_expires_at

C. TTL Requirements

The dedupe window MUST be declared per command (CRCD). Defaults:

  • SHOULD be ≥ 24 hours for financial/critical commands
  • MAY be shorter for low-impact mutations if safe

If TTL expires, the command MAY execute again; therefore TTL must be chosen to prevent unacceptable duplicate effects.

D. Collision Handling

If a collision is detected (same idempotency key but envelope differs), the system MUST:

  • reject the new command as execution.rejected with reason idempotency_conflict, and
  • emit evidence capturing both envelope fingerprints (redacted as needed)

IX. Outcome Replay Semantics

A. Replay Requirement

If a duplicate idempotency key is received within the active window, the system MUST NOT re-execute side effects. It MUST return:

  • the same terminal outcome, or
  • a reference to the same terminal evidence chain

B. In-Progress Duplicates

If the first attempt is in_progress, duplicates MUST return a stable response indicating:

  • “processing” status
  • correlation identifiers
  • how to query OoC status

The system MUST NOT spawn parallel executions for the same key.

C. Deterministic Response Surface

User-facing conversational responses SHOULD be stable across replays (same summary, same identifiers), subject to redaction policy.

X. Confirmation and Step-up Binding

For destructive/admin commands requiring confirmation and/or step-up:

  • Confirmation tokens MUST be bound to command_id AND idempotency_key.
  • A confirmation token MUST be single-use and short-lived.
  • A replayed duplicate MUST NOT require re-confirmation if the original is already confirmed and executed; instead it MUST replay the outcome.

This prevents a replay attempt from forcing repeated human confirmations or bypassing them.

XI. Shielding Non-Idempotent External Effects

Some external systems are not safely idempotent (e.g., legacy payment capture endpoints without idempotency support).

For commands classified I3, the system MUST implement at least one shielding strategy:

  • S1: External idempotency support (pass an idempotency key to provider)
  • S2: Transactional outbox + single dispatcher (ensures one external call)
  • S3: “Effect ledger” recorded before calling provider, with strict replay rules
  • S4: Provider-side reconciliation + compensation plan (RCP) if duplicates occur

Systems MUST declare which strategy is used per command in CRCD.

XII. Evidence Requirements for Idempotency Decisions

When deduplication occurs, the system MUST emit EAS evidence such that an auditor can verify:

  • whether execution was performed or replayed
  • original command_id and idempotency_key
  • dedupe decision (first_seen | duplicate_replayed | conflict_rejected)
  • the outcome reference returned

This MAY be expressed as observation.emitted or included in normal execution artifacts.

XIII. Conformance Tests (Minimum)

An IDS-compliant implementation MUST pass tests demonstrating:

  1. Duplicate deliveries of the same mutation do not duplicate effects
  2. Concurrent duplicates converge to one execution
  3. Duplicate after success replays outcome
  4. Duplicate during in-progress returns processing status
  5. Collision case rejects with evidence
  6. Confirmation binding prevents bypass or double-confirmation abuse

XIV. Relationship to Other RFCs

  • WFCS (RFC-WF-0001): requires WhatsApp-first reliability under real delivery conditions.
  • CCP (RFC-WF-0003): provides canonical envelopes and confirmation semantics.
  • CRCD (RFC-WF-0005): declares idempotency class and TTL per command.
  • EAS (RFC-WF-0006): records replay/dedupe decisions and outcomes.
  • TMSI (RFC-WF-0009): maps replay and duplicate abuse threats to IDS mitigations.

XV. Security Considerations

Idempotency infrastructure is a high-value target. Implementations MUST:

  • scope dedupe keys by tenant (mandatory)
  • protect dedupe store from tampering
  • rate-limit repeated duplicate submissions
  • ensure replay does not leak sensitive details beyond actor privilege

XVI. Conclusion

IDS standardizes the mechanics required to achieve exactly-once effects on top of at-least-once delivery realities. By enforcing canonical key derivation, atomic dedupe semantics, outcome replay, and evidence-backed decisions, WhatsApp-first systems can remain safe, auditable, and operational under duplicates, retries, and real-world messaging behavior.

References

[1] RFC-WF-0001, WhatsApp-First Compliance Core (WFCS).
[2] RFC-WF-0003, Conversational Command Protocol (CCP).
[3] RFC-WF-0005, Command Registry & Capability Declaration (CRCD).
[4] RFC-WF-0006, Evidence Artifact Schema (EAS).
[5] RFC-WF-0009, Threat Model & Security Invariants (TMSI).

Concepts and Technologies

At-least-once delivery, exactly-once effects, idempotency keys, deduplication stores, atomic check-and-set, outcome replay, transactional outbox, effect ledger, collision rejection, confirmation binding, evidence-backed dedupe decisions.

Top comments (0)