Proposal: A Standardized Data & State Layer for Agentic AI

[antunjurkovic-collab]

Executive Summary

The WordPress AI ecosystem has successfully defined Transport (WP AI Client SDK) and Logic (Abilities API). However, a standardized Data & State Layer is currently missing.

Current AI experiments rely on parsing raw HTML (post_content) and standard database writes. This results in:

• High Token Costs: ~56% of tokens are wasted on HTML markup, _links, and metadata.
• High Infrastructure Load: Standard API requires 56% more database queries and 100% more memory allocation.
• Safety Risks: Lack of concurrency control leads to race conditions (AI overwriting human edits).
• Brittle Logic: Abilities must implement complex regex/parsing logic to understand content.

We propose Dual-Native API as the standardized I/O Layer to complete the stack. It provides a Machine Representation (MR) for efficient reading and a Safe Write API for atomic, conflict-free editing.

---

1. Strategic Alignment: The "Fourth Building Block"

In the AI Building Blocks roadmap, three blocks were identified. We believe the Data Layer is the necessary fourth block to make the system production-ready and scalable.

Layer	Component	Status	Function
1. Interface	MCP Adapter	🟢 Core	Exposes tools to Agents
2. Logic	Abilities API	🟢 Core	Defines what to do (Routing/Schema)
3. Transport	WP AI Client	🟢 Core	Handles connectivity & Auth
4. Data	Dual-Native API	🟡 Proposed	Handles State, Safety, and I/O

---

2. Solving the "Functional Core" Input Problem

The recent post Meet Abilities: WordPress' New Functional Core argues for composable, pure functions. However, functions require Structured Inputs.

Dual-Native acts as the "Type System" for Content Abilities.

Instead of summarize( html_string ), we have summarize( MR_Object ). This makes Abilities cleaner, faster, and purely focused on logic.

---

3. Technical Architecture: The Dual-Native Pattern

The API synchronizes the Human View (HTML) with a Machine View (JSON).

A. The Read Path: Machine Representation (MR)

We expose a JSON envelope containing the logical Block Graph, stripped of theme markup and HTML comments.

Production Metrics (tested on galaxybilliard.club with 13 plugins including WooCommerce + Yoast SEO):

Metric	Standard API (/wp/v2/posts)	Dual-Native API	Improvement
Response Time	96 ms	8 ms	92% faster
Database Queries	18 queries	8 queries	56% fewer
Memory Allocation	2 MB	0 MB	100% less
Payload Size	17.94 KB avg	8.65 KB avg	56% smaller
Token Usage	4,593 tokens	2,214 tokens	56% fewer

Key Features:

• Integrity: Includes Content-Digest (RFC 9530) headers computed over final wire bytes.
• Zero-Fetch: Implements strong ETags (CIDs) to allow Agents to skip processing unchanged content (returning 304 Not Modified).
• Infrastructure Efficiency: Bypasses heavy the_content filters, oEmbed processing, and hypermedia generation.

See: BENCHMARK.md for AI cost analysis and PERFORMANCE.md for infrastructure metrics.

---

B. The Write Path: Atomic Mutations & Safety

We introduce a Safe Write API (/blocks) that handles server-side block serialization.

Atomic Operations:
Agents send intents like append, prepend, or insert (with index). The server handles the HTML generation, preventing layout corruption.

Optimistic Locking:
The API enforces If-Match headers using the content hash (CID).

Example Scenario:

1. Agent reads post (receives ETag: "sha256-abc123...")
2. Agent generates title based on content
3. Human edits the post (CID changes to "sha256-xyz789...")
4. Agent attempts write with If-Match: "sha256-abc123..."
5. Server returns 412 Precondition Failed
6. Agent detects conflict, re-reads new state, and retries

Result: Zero data loss. The Agent's update is based on the latest content, not stale state.

---

4. Integration Plan: The "Agentic Bridge"

To demonstrate composability, we built a reference implementation (wp-dual-native-abilities) that bridges all four building blocks.

The Workflow: "Agentic Summarize"

1. Ability (Logic): dni/agentic-summarize is triggered
2. Data (Dual-Native): Fetches the MR (saving 56% tokens, 56% queries)
3. Transport (SDK): Uses WordPress\AI_Client\AI_Client to send clean text to LLM
4. Safety (Dual-Native): Appends summary with Optimistic Locking using current CID

Fallback Behavior:

• If WP AI Client is not installed: Falls back to deterministic heuristic
• If Abilities API is not installed: Falls back to REST polyfill endpoints

---

Live Validation (MCP)

We connected this stack to Anthropic's Model Context Protocol via Claude Desktop.

Demonstrated Capabilities:

1. Self-Healing: Claude detected a block order error via MR and autonomously fixed it using atomic moves.

   "Read post 130, analyze block structure, fix ordering issues"
   → Agent used dni/get-post-mr to identify incorrect heading sequence
   → Applied atomic insert operations with If-Match guards
   → Result: Content fixed without manual intervention
   

2. Data Science: Claude used Code Execution (Python) to analyze the Catalog and plot content statistics instantly, treating WordPress as a structured dataset.

   "Analyze my publishing frequency over the last 50 posts"
   → Agent fetched dni/get-catalog with date filters
   → Used Python MCP server to process and visualize data
   → Result: Publication pattern analysis without custom dashboards
   

---

5. Production Validation

Test Site: https://galaxybilliard.club

Environment:

• 13 active plugins (WooCommerce, Yoast SEO, Query Monitor)
• Production WordPress with real content and traffic
• "Heavy Real-World Site" scenario

Validation Results:

• ✅ All abilities tested and functional
• ✅ Zero-fetch optimization working (100% cache hit rate)
• ✅ Optimistic locking preventing race conditions
• ✅ ETag/CID parity verified with RFC 9530 Content-Digest
• ✅ 304 Not Modified responses confirmed

Validation Tools Available:

# Included in wp-dual-native/tools/validator/
python benchmark_api_vs_dni.py        # A/B test Standard vs Dual-Native
python measure_dni_savings.py         # HTML vs MR comparison
python dual_native_validate.py        # API integrity validation

---

6. Roadmap & Collaboration

We propose adding Dual-Native as an infrastructure experiment to the WordPress/wordpress-develop or WordPress/ai repository.

Phased Integration:

Phase 1: Bridge (Available Now)

• We provide the wp-dual-native-abilities addon
• Registers endpoints as standard Abilities:
  • dni/get-post-mr - Read Machine Representation
  • dni/get-post-md - Read Markdown
  • dni/get-catalog - Content discovery
  • dni/insert-blocks - Safe atomic writes
  • dni/generate-title - AI title generation
  • dni/ai-suggest - Summary & tag suggestions
  • dni/agentic-summarize - Full workflow reference

Phase 2: Experiments (Immediate Benefits)

• Refactor existing AI experiments to use Dual-Native:
  • Title Generation: Use dni/get-post-mr for context (saves 56% tokens)
  • Title Generation: Use dni/generate-title for updates (prevents race conditions)
  • Content Analysis: Use structured blocks instead of HTML parsing
  • Bulk Operations: Use catalog + zero-fetch for efficient scanning

Phase 3: Core Integration (Long-term)

• As the Abilities API matures, this serves as the reference implementation
• Core consideration: "How should WordPress handle Agentic I/O?"
• Potential Core PR: "Add content API with strong validators and atomic mutations"

---

7. Resources & Documentation

Repositories:

• Architecture Spec: antunjurkovic-collab/dual-native-pattern
• Data Layer Plugin: antunjurkovic-collab/wp-dual-native
• Abilities Bridge: antunjurkovic-collab/wp-dual-native-abilities

Benchmarks & Analysis:

• BENCHMARK.md - AI cost analysis (56% token savings, $60-70/year savings per 10K operations)
• PERFORMANCE.md - Infrastructure metrics (92% faster, 56% fewer queries, 0MB memory overhead)

Validation Tools:

• Python scripts for reproducing benchmarks
• API integrity validators
• Production site examples

---

8. Cost-Benefit Analysis

For AI Teams:

• 56% fewer tokens → Lower LLM costs ($60-70/year per 10K operations)
• Structured input → Simpler ability logic
• Zero-fetch → Skip unchanged content entirely

For Infrastructure Teams:

• 92% faster responses → Better user experience
• 56% fewer database queries → Reduced DB load (10M queries saved annually at scale)
• 100% less memory allocation → Improved server density
• 60% bandwidth savings → Lower CDN costs

For Core Contributors:

• Reference implementation → Guides future API design
• Production-tested → Real-world validation on heavy sites
• Composable → Works with or without Abilities API
• RFC-compliant → Uses standard HTTP headers (ETag, If-Match, Content-Digest)

---

9. Question for the AI Core Team

Does this "Data Layer" approach align with the architectural vision for the next phase of AI Experiments?

We believe the four-layer model (Interface + Logic + Transport + Data) creates a complete, production-ready foundation for agentic WordPress applications.

We are ready to contribute the code, documentation, and validation tools.

Next Steps:

1. Review the architecture and benchmarks
2. Test the bridge plugin with existing AI experiments
3. Provide feedback on API design and integration approach
4. Discuss potential paths to Core or wordpress-develop

---

Contact:

• GitHub: @antunjurkovic-collab
• Slack: @antju
• Production Demo (test wesite): https://galaxybilliard.club
• Documentation: See repository README files

License: GPL v2 or later (WordPress-compatible)

---

Document Version: 1.0
Last Updated: November 2025