DEV Community

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

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0030

#webdev #programming #opensource #rfc

RFC-WF-0030

Evidence Query & Retrieval Protocol (EQRP)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0006 (EAS), RFC-WF-0007 (OoC), RFC-WF-0013 (WKD), RFC-WF-0010 (IDS), RFC-WF-0021 (SECR), RFC-WF-0015 (PPGP)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies the Evidence Query & Retrieval Protocol (EQRP) for WhatsApp-first systems. EQRP defines a standard query interface for retrieving Evidence Artifacts (EAS) in a secure, scope-gated, redaction-aware way. EQRP standardizes query inputs (by command_id, correlation_id, artifact_id, time windows), pagination, filtering, sorting, and response envelopes, enabling interoperable tooling (auditors, OoC drill-down, CATS) without bespoke evidence-store integrations.

Index Terms— evidence retrieval, query protocol, audit APIs, pagination, filtering, redaction, interoperability.

I. Introduction

EAS defines the evidence artifact schema. OoC requires that users can drill down into evidence via conversation. CATS and third-party tools need a consistent way to fetch evidence for audits and verification. Without a standardized evidence query contract, every implementation invents its own endpoint shape, pagination semantics, and filtering rules—breaking interoperability.

EQRP standardizes evidence retrieval as a protocol.

II. Scope

EQRP specifies:

  • A canonical HTTP query endpoint shape (method + payload)
  • Query fields and minimum supported filters
  • Pagination and sorting semantics
  • Response envelope (data + page info + redaction info)
  • Authorization and redaction requirements (ACSM/PPGP-aligned)
  • Error codes and safe failure behaviors
  • Discovery advertisement via WKD

EQRP does not mandate a database schema or indexing strategy.

III. Normative Language

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

IV. Definitions

Evidence Query: A request that retrieves EAS artifacts matching constraints.
Result Page: A bounded subset of results with a continuation token.
Redaction Policy: The policy governing what fields are masked/dropped for a caller.

V. Design Goals

EQRP MUST ensure:

  • G1. Interoperability: same query works across implementations.
  • G2. Safety: scope-gated and redaction-aware outputs.
  • G3. Determinism: stable sorting/pagination.
  • G4. Toolability: supports audits, OoC drill-down, and incident workflows.
  • G5. Minimal Required Support: small base query set, extensible via SECR.

VI. Canonical Endpoint

A. Endpoint Location

Systems SHOULD expose:

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

WKD MUST advertise the endpoint under endpoints.evidence_query.url if present.

B. Content Types

  • Request: application/json
  • Response: application/json

VII. Query Request Schema (Normative Minimum)

A. Required Behavior

Implementations MUST support querying by at least one of:

  • command_id
  • correlation_id
  • artifact_id

B. Supported Filters (Minimum Set)

Implementations MUST support:

  • artifact_type filter (single or list)
  • time_range filter (from, to)
  • lifecycle.stage filter (single or list)

C. Pagination (Required)

Implementations MUST support:

  • page.size (default and max enforced)
  • page.cursor (opaque continuation token)

D. Sorting (Required)

Implementations MUST support sorting by:

  • emitted_at ascending/descending (default: ascending)

E. Canonical Request Example 

{
  "query": {
    "command_id": "cmd_123",
    "artifact_type": ["execution.executed", "execution.failed", "authz.decided"],
    "time_range": { "from": "2026-02-22T00:00:00Z", "to": "2026-02-22T23:59:59Z" },
    "lifecycle_stage": ["executed", "failed", "rejected"]
  },
  "sort": { "by": "emitted_at", "order": "asc" },
  "page": { "size": 50, "cursor": null }
}
Enter fullscreen mode Exit fullscreen mode

VIII. Response Envelope (Normative)

The response MUST include:

  • data[] — list of EAS artifacts (or redacted forms of them)
  • page — pagination info
  • redaction — applied redaction policy metadata
  • meta — optional diagnostics (counts, timings)

Canonical Response Example 

{
  "data": [
    { "eas_version": "1.0.0", "artifact_id": "artifact_1", "artifact_type": "authz.decided", "...": "..." }
  ],
  "page": {
    "size": 50,
    "cursor_next": "opaque-token-or-null"
  },
  "redaction": {
    "policy_id": "redact.default",
    "fields_dropped": ["payload.raw_input.audio_transcript"],
    "fields_masked": ["subject.actor.display_name"]
  },
  "meta": {
    "returned": 1,
    "server_time_ms": 12
  }
}
Enter fullscreen mode Exit fullscreen mode

If cursor_next is null, no more pages exist.

IX. Authorization and Redaction (Normative)

A. Scope Gating

Evidence queries MUST be scope-gated. At minimum:

  • querying by command_id SHOULD be allowed for the command’s actor (policy-defined)
  • cross-actor or tenant-wide queries MUST require privileged scopes

B. Tenant Isolation

EQRP MUST enforce tenant scoping; cross-tenant evidence access is forbidden.

C. Redaction Enforcement

Responses MUST apply redaction according to PPGP policies. The response MUST declare which redaction policy was applied.

X. Error Model (Normative)

Implementations MUST return structured errors:

  • invalid_query (missing required selector)
  • unauthorized (no auth)
  • forbidden (insufficient scope)
  • not_found (no artifacts or command unknown, policy-defined)
  • rate_limited (RAOS)
  • server_error

Errors MUST be safe (no leaking sensitive existence info across tenants).

Example:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient scope for evidence query.",
    "retryable": false
  }
}
Enter fullscreen mode Exit fullscreen mode

XI. OoC Integration (Normative)

OoC drill-down features MUST be implementable using EQRP:

  • “show evidence for command_id” → EQRP query by command_id
  • “show artifact #3” → EQRP query by artifact_id
  • “show last error chain” → EQRP filter by artifact types/stages

XII. Extensions (SECR)

Implementations MAY add:

  • additional filters (by actor_id, service, environment, registry_ref.command_name)
  • aggregation queries (counts per type)
  • streaming mode

Such additions MUST use extensions / x_* fields and MUST NOT break core request/response parsing.

XIII. Security Considerations

Evidence APIs are sensitive. Implementations MUST:

  • apply strict redaction by default
  • rate-limit queries (RAOS-aligned)
  • log evidence access (telemetry and/or evidence)
  • prevent enumeration attacks via consistent error behavior

XIV. Conclusion

EQRP standardizes the missing interop layer between “we have evidence” and “we can actually use it.” By defining a minimal, redaction-aware, scope-gated evidence query protocol, WhatsApp-first implementations become toolable for audits, incident response, and conversational drill-down—without bespoke integrations.

References

[1] RFC-WF-0006, Evidence Artifact Schema (EAS).
[2] RFC-WF-0007, Observability over Conversation (OoC).
[3] RFC-WF-0013, Well-Known Discovery & Interop Endpoints (WKD).
[4] RFC-WF-0010, Idempotency & Delivery Semantics (IDS).
[5] RFC-WF-0021, Schema Extensions & Compatibility Rules (SECR).
[6] RFC-WF-0015, Policy Packs & Governance Profiles (PPGP).

Concepts and Technologies

Evidence retrieval APIs, cursor pagination, filterable audit logs, redaction metadata, scope-gated queries, tenant isolation, OoC drill-down backends, schema extension points.

Top comments (0)