DEV Community

suissAI
suissAI

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0024

#webdev #programming #rfc #whatsapp

RFC-WF-0024

Connector Contracts & Outbox/Inbox Interop (CCOI)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0003 (CCP), RFC-WF-0005 (CRCD), RFC-WF-0006 (EAS), RFC-WF-0008 (RCP), RFC-WF-0010 (IDS), RFC-WF-0018 (SMCL), RFC-WF-0021 (SECR)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies Connector Contracts & Outbox/Inbox Interop (CCOI) for WhatsApp-first systems. CCOI defines normative contracts for integrating external systems (payments, ERP, shipping, analytics) through standardized connector interfaces and outbox/inbox patterns that preserve idempotency, evidence traceability, and recovery semantics. CCOI standardizes effect messages, delivery acknowledgements, retry behavior, and connector-side idempotency requirements, enabling exactly-once effects across non-idempotent external APIs using governed execution and compensations.

Index Terms— connectors, outbox pattern, inbox pattern, integration contracts, idempotency, exactly-once effects, retries, reconciliation, compensation.

I. Introduction

WhatsApp-first systems often orchestrate real business effects via third parties: charge a card, create shipment labels, sync inventory, issue invoices. The core WhatsApp-first stack (CCP/IDS/EAS/RCP/SMCL) can be correct internally and still fail externally if connectors are ad hoc: duplicated charges, inconsistent retries, no reconciliation, and weak evidence binding.

CCOI standardizes connector integration so that external side effects become as governed and auditable as internal effects.

II. Scope

CCOI specifies:

  • Connector interface obligations (request/response semantics)
  • Standard Effect Envelope for external calls
  • Outbox/inbox semantics for reliable delivery and dedupe
  • Connector acknowledgement and state model alignment (SMCL)
  • Evidence emission requirements for external effects (EAS)
  • Retry/backoff and reconciliation rules
  • Compensation and rollback mapping for external effects (RCP)
  • Compatibility and extension rules (SECR)

CCOI does not mandate a specific queue or ESB; it defines behavior.

III. Normative Language

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

IV. Definitions

Connector: A component that integrates with an external system.
Outbox: A reliable, append-only store of pending external effects to dispatch.
Inbox: A dedupe store on the receiver side to ensure exactly-once processing.
Effect: An externally visible side effect (charge, shipment, invoice, etc.).
Effect Envelope: Canonical representation of an effect request with trace and idempotency bindings.

V. Design Goals

CCOI MUST ensure:

  • G1. Exactly-once effects across external calls under duplicates/retries.
  • G2. Evidence traceability from WhatsApp message → command → effect → outcome.
  • G3. Governed retries with backoff and loop prevention.
  • G4. Recovery compatibility (retry/reprocess/compensate) for external effects.
  • G5. Interop portability: swap connectors without breaking governance semantics.

VI. Effect Envelope (Normative)

Every external call initiated by a command MUST be represented as an Effect Envelope.

A. Required Fields

  • effect_id (unique)
  • command_id (originating command)
  • idempotency_key (derived from command + effect type + target)
  • effect_type (e.g., payment.capture, shipping.create_label)
  • target (external resource identifiers if known)
  • payload (connector-specific request body; redacted in evidence outputs when needed)
  • trace (correlation_id, conversation_id, message_ids)
  • attempt (integer)
  • created_at
  • policy_refs (optional; applied governance policies)

B. Canonical Example 

{
  "effect_id": "uuid",
  "command_id": "cmd_123",
  "idempotency_key": "sha256(...)",
  "effect_type": "payment.capture",
  "target": { "order_id": "204" },
  "payload": { "amount": 1990, "currency": "BRL" },
  "trace": {
    "correlation_id": "corr_789",
    "conversation_id": "conv_123",
    "message_ids": ["wamid.xxx"]
  },
  "attempt": 1,
  "created_at": "2026-02-22T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

VII. Outbox Semantics (Normative)

A. Write-before-dispatch

Before calling an external system, the system MUST persist the Effect Envelope to an outbox (append-only or equivalent durable record).

B. Single Dispatcher Rule

Effects MUST be dispatched by a controlled dispatcher that enforces:

  • dedupe by idempotency_key
  • retry/backoff policy
  • attempt counters
  • stable outcome recording

C. Outbox State

Outbox entries MUST track:

  • pending | dispatched | acknowledged | failed | compensated | dead_letter

VIII. Inbox Semantics (Connector Side)

If the connector receives effect envelopes (e.g., internal connector service):

  • it MUST implement an inbox dedupe keyed by idempotency_key
  • duplicates MUST replay the prior outcome (not re-execute)
  • acknowledgements MUST be idempotent

If the connector calls a third-party API directly (no inbox), it MUST use provider idempotency when available (Section IX).

IX. Connector Idempotency Requirements

A. Provider Idempotency (Preferred)

If the external provider supports idempotency keys, the connector MUST pass idempotency_key.

B. If Provider Has No Idempotency

The system MUST implement shielding strategies (IDS-aligned), such as:

  • effect ledger + strict replay
  • reconciliation checks before issuing calls
  • manual approval gating for retries after uncertainty
  • compensation plan readiness (RCP)

X. Acknowledgement Contract

Connectors MUST return an acknowledgement containing:

  • effect_id
  • status (acknowledged | rejected | failed | pending)
  • provider_ref (external reference id if any)
  • timestamp
  • retryable boolean (when failed)

Acknowledgements MUST be stored and linked to evidence artifacts.

XI. Evidence Emission Requirements (EAS)

External effects MUST emit evidence sufficient to prove:

  • effect was created (outbox write)
  • effect was dispatched
  • acknowledgement received and status
  • any retries and final outcome
  • links back to originating command and trace ids

Evidence MUST redact sensitive payload fields under DRPC/PPGP rules, but MUST preserve enough to audit correctness.

XII. Recovery and Compensation Mapping (RCP)

For effects that can fail or be uncertain, systems MUST define recovery actions:

  • retry effect dispatch (governed)
  • reprocess from checkpoint (if supported)
  • compensate (refund, void, cancel label, etc.)

Compensation plans MUST be declared for effect types where external side effects are irreversible or high-risk.

XIII. Lifecycle Alignment (SMCL)

Effect execution MUST align to lifecycle stages:

  • command started MAY spawn effects
  • command executed MUST NOT be reached until required effects are acknowledged or policy marks them as async-completable
  • failures in required effects MUST transition command to failed or blocked according to policy

Asynchronous completion policies MUST be explicit and evidence-backed.

XIV. Compatibility and Extensions (SECR)

Connector envelopes MAY include extensions or x_* fields, but:

  • core fields MUST remain stable
  • connector-specific payloads MUST be encapsulated under payload
  • consumers MUST ignore unknown extension fields safely

XV. Conformance Tests (TVRS/CATS Alignment)

Implementations SHOULD demonstrate:

  • duplicate effect envelope does not duplicate provider-side effects
  • retries respect backoff and attempt caps
  • evidence chain links command → effect → provider_ref
  • compensation works for at least one effect type in sandbox

XVI. Security Considerations

Connector payloads often include sensitive data. Implementations MUST:

  • redact secrets in evidence and OoC views
  • scope connector operations by tenant
  • rate-limit retries to prevent accidental fraud
  • audit connector configuration changes via ACSM/HAPF policies (where applicable)

XVII. Conclusion

CCOI makes external integrations first-class citizens in the WhatsApp-first governance model. By enforcing effect envelopes, outbox/inbox semantics, idempotent acknowledgements, evidence traceability, and governed recovery/compensation, WhatsApp-first systems can safely execute real business operations across unreliable networks and third-party APIs.

References

[1] RFC-WF-0003, Conversational Command Protocol (CCP).
[2] RFC-WF-0005, Command Registry & Capability Declaration (CRCD).
[3] RFC-WF-0006, Evidence Artifact Schema (EAS).
[4] RFC-WF-0008, Recovery & Compensation Protocol (RCP).
[5] RFC-WF-0010, Idempotency & Delivery Semantics (IDS).
[6] RFC-WF-0018, State Model & Command Lifecycle (SMCL).
[7] RFC-WF-0021, Schema Extensions & Compatibility Rules (SECR).

Concepts and Technologies

Effect envelopes, outbox/inbox patterns, provider idempotency keys, acknowledgement contracts, retry/backoff, reconciliation, evidence traceability, governed compensation plans, external side-effect shielding, connector interoperability.

Top comments (0)