DEV Community

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

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0027

#webdev #programming #opensource #rfc

RFC-WF-0027

Reference Implementation Requirements (RIR)

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

Abstract

This document specifies Reference Implementation Requirements (RIR) for WhatsApp-first systems. RIR defines the minimal architectural components, interfaces, and behaviors a reference implementation (mini-framework / PoC) MUST provide to be considered a faithful implementation of the WhatsApp-first Specification. RIR standardizes required modules (adapter, command engine, security, evidence, observability, recovery), their minimum APIs, expected outputs, and conformance hooks for CATS/TVRS—enabling reproducible implementations and comparable PoCs across languages and stacks.

Index Terms— reference implementation, minimal framework, architecture requirements, interoperability, conformance hooks, WhatsApp-first.

I. Introduction

Specs become actionable when developers can run them. A reference implementation doesn’t need to be production-grade, but it MUST encode the non-negotiable semantics: canonical command execution, scope/step-up gating, evidence emission, conversational observability, and governed recovery with idempotency.

RIR defines what “counts” as a valid mini-framework PoC for WFS, ensuring PoCs do not skip the hard parts (idempotency/evidence/recovery) while claiming compliance.

II. Scope

RIR specifies:

  • Minimal modules required in a reference implementation
  • Module boundaries and APIs (language-agnostic contracts)
  • Required data artifacts (CRCD, EAS, policies) and endpoints (WKD)
  • Required conformance hooks for CATS/TVRS
  • Minimal operational capabilities to demonstrate end-to-end flows
  • Non-goals (what the PoC may omit safely)

RIR does not mandate cloud providers or specific libraries.

III. Normative Language

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

IV. Definitions

Reference Implementation: A runnable system demonstrating the specification’s core semantics.
Mini-framework: A reusable set of components implementing WFS primitives.
PoC: Proof-of-concept demonstrating end-to-end behavior, may be simplified.

V. Design Goals

RIR MUST ensure:

  • G1. End-to-End Demonstrability: WhatsApp message → command → evidence → OoC → recovery
  • G2. Minimal but Complete: small surface area, but no skipping invariants
  • G3. Toolable: works with CATS/TVRS (audit hooks)
  • G4. Portable: can be implemented in TS/Python/Go/etc.
  • G5. Safe by Default: sandbox mode, controlled mutations, redaction

VI. Required Modules (Normative)

A reference implementation MUST include these modules (may be in-process or separated):

M1 — Channel Adapter (CAMN)

  • Ingest inbound messages and normalize into NMEs
  • Support text + audio (STT transcript attachment)
  • Produce stable conversation_id and message_id bindings

M2 — Command Engine (CCP + SMCL)

  • Canonicalize inputs into Command Envelopes
  • Enforce lifecycle ordering and states (SMCL)
  • Support confirmations for mutations (including strengthened for destructive)

M3 — Authorization & Step-up (ACSM)

  • Scope evaluation per command
  • Trust level model (L1/L2/L3)
  • Step-up enforcement for S3/R3 (can be mocked but must be enforceable)

M4 — Idempotency Layer (IDS)

  • Dedupe store with atomic check-and-set
  • Outcome replay for duplicates
  • TTL configuration per command class (policy-driven)

M5 — Evidence Writer (EAS)

  • Emit EAS artifacts for each lifecycle transition
  • Append-only semantics (no mutations)
  • Integrity fields (hash) recommended; at minimum schema compliance

M6 — Conversational Observability (OoC)

  • Provide status for command_id
  • Explain rejection/failure reasons
  • Evidence drill-down with redaction policy

M7 — Recovery & Compensation (RCP)

  • RCP.OPTIONS, RCP.RETRY, RCP.CANCEL, RCP.REPROCESS, RCP.COMPENSATE (as applicable)
  • Evidence emission for recovery actions
  • Attempt caps/backoff behavior can be simplified but must exist

M8 — Registry & Policies (CRCD + PPGP)

  • Provide CRCD registry declaring capabilities/commands
  • Provide policy pack/profile binding for confirmation/step-up/redaction/idempotency
  • Commands must reference policy ids

M9 — Discovery (WKD)

  • Provide /.well-known/wfs.json
  • Provide default CRCD and EAS schema endpoints (or redirects)

M10 — Audit Hooks (CATS/TVRS)

  • Provide a sandbox tenant/test mode
  • Provide evidence query capability (at least by command_id)
  • Provide ability to run test vectors safely

VII. Minimum Public Interfaces (Language-Agnostic)

A. Registry Endpoint

  • GET /.well-known/wfs/crcd.json → CRCD registry document

B. Discovery Endpoint

  • GET /.well-known/wfs.json → WKD discovery doc

C. Evidence Query Endpoint (Minimum)

  • POST /.well-known/wfs/evidence/query

    • input: { "command_id": "..." }
    • output: list of EAS artifacts (redacted by policy)

D. Minimal Command Surface

  • conversational triggers for:

    • one read-only OoC query
    • one mutation requiring confirmation
    • one destructive requiring strengthened confirmation
    • one recovery action (retry) demonstrated end-to-end

VIII. Required Demonstration Scenarios (Normative)

A reference implementation MUST demonstrate:

  1. Duplicate delivery of a mutating command does not duplicate effects (IDS)
  2. Confirmation gating for mutation and strengthened for destructive (CCP)
  3. Scope denial produces explainable rejection (ACSM + OoC)
  4. Evidence emission across lifecycle transitions (EAS + SMCL)
  5. OoC drill-down retrieves evidence summaries safely (OoC + DRPC/PPGP)
  6. Recovery flow (retry or compensate) executes with evidence (RCP)

These scenarios MUST be runnable in sandbox mode and SHOULD be expressed in TVRS format.

IX. Non-Goals (Allowed Omissions)

A PoC MAY omit:

  • production-grade encryption and key management (but MUST enforce ACSM gates)
  • full multi-tenant scaling (but MUST support tenant scoping logically)
  • full connector ecosystem (CCOI) beyond one mock connector
  • full UI richness (TUXP beyond minimum templates)
  • advanced agent autonomy (AIP beyond proposal/execution separation)

However, the PoC MUST NOT omit: envelope execution, idempotency, evidence, OoC, and governed recovery.

X. Conformance Claim Rules

A reference implementation MAY claim:

  • “WFS PoC Conformant” only if all required modules and scenarios pass.
  • It MUST publish the versions of WFS/RCMC/CATS it targets in wfs.json.

XI. Security Considerations

PoCs often cut corners. RIR prevents unsafe claims by requiring the core invariants. Sandbox mode is mandatory to prevent accidental destructive actions during demos. Evidence and redaction must be enforced even in PoC to avoid leaking sensitive data in conversational outputs.

XII. Conclusion

RIR defines what a real WhatsApp-first mini-framework must include: not just a bot loop, but canonical commands, security gates, idempotency, evidence, conversational observability, and recovery. This makes PoCs comparable, toolable, and honest—paving the way for monthly module releases while maintaining spec integrity.

References

[1] RFC-WF-0003, Conversational Command Protocol (CCP).
[2] RFC-WF-0004, Administrative Command Security Model (ACSM).
[3] RFC-WF-0005, Command Registry & Capability Declaration (CRCD).
[4] RFC-WF-0006, Evidence Artifact Schema (EAS).
[5] RFC-WF-0007, Observability over Conversation (OoC).
[6] RFC-WF-0008, Recovery & Compensation Protocol (RCP).
[7] RFC-WF-0010, Idempotency & Delivery Semantics (IDS).
[8] RFC-WF-0011, Compliance Audit Toolkit Spec (CATS).
[9] RFC-WF-0014, Channel Adapter & Message Normalization (CAMN).
[10] RFC-WF-0018, State Model & Command Lifecycle (SMCL).
[11] RFC-WF-0021, Schema Extensions & Compatibility Rules (SECR).
[12] RFC-WF-0024, Connector Contracts & Outbox/Inbox Interop (CCOI).

Concepts and Technologies

Mini-framework requirements, module boundaries, normalized message events, command envelopes, scope/step-up gates, dedupe/outcome replay, evidence writer, conversational observability, governed recovery, well-known discovery, audit hooks, sandbox conformance scenarios.

Top comments (0)