Version: 1.3 Last Updated: November 2025 Status: Draft for Review
Feedback: Report issues or suggest improvements at GitHub Issues
This repository contains the complete Dual-Native Pattern document suite—an architectural approach for synchronizing Human Representation (HR) and Machine Representation (MR) to enable safe, deterministic reading and writing by AI agents.
The pattern is proven at scale through multiple implementations: the Collaboration Tunnel Protocol (TCT) demonstrating 83% bandwidth savings for content distribution, and production WordPress deployments (wp-dual-native plugin) enabling safe agentic editing with optimistic concurrency control and block-level atomic operations.
The Dual-Native Pattern provides a formal architecture for systems serving both human and AI users with safe read/write capabilities:
- Every resource has two synchronized representations: HR (Human-optimized: HTML, dashboards, PDFs) and MR (Machine-optimized: JSON APIs, FHIR, Avro). MR may be offered in multiple profiles (structured JSON/Avro, text/Markdown, binary/CBOR) optimized for different consumption patterns.
- Bidirectional linking: Navigate seamlessly between HR ↔ MR with explicit links (not just documentation)
- Semantic equivalence: HR and MR represent the same content at the same point in time, verified through Content Identity validators (CID)
- Zero-fetch optimization: AI agents skip redundant downloads when CID matches cached version (83% bandwidth savings observed)
- Structural Mutations: AI agents can safely modify system state via the MR without corrupting the HR, using atomic operations and optimistic concurrency (demonstrated in WordPress, Stripe, GitHub)
Real-world evidence: 11+ platforms already implement informal dual-native patterns for reading (Stripe, GitHub, Databricks, Wikidata). Write capabilities are demonstrated through production WordPress deployments and validated via Model Context Protocol (MCP) integrations. See Case Library for detailed analysis.
This suite consists of three core documents at the repository root:
dual-native-pattern/
├── README.md ← You are here (start here!)
├── WHITEPAPER.md ← [1] Non-normative whitepaper
├── CORE-SPEC.md ← [2] Normative specification
├── IMPLEMENTATION-GUIDE.md ← [3] Domain implementation cookbook (includes optional enhancements)
├── CHANGELOG.md ← Version history
├── bindings/ ← Technology bindings (HTTP, SQL, Streaming, Object Storage)
│ ├── README.md
│ ├── http-rest.md
│ └── ...
└── cases/ ← Platform case studies
├── README.md
├── index.json ← Machine-readable catalog
├── github.md
├── stripe.md
└── ...
The following companion documents are planned for future release:
- Security & Governance Guide (planned) — Comprehensive threat models, domain-specific attack vectors, detailed mitigations, incident response playbooks, and governance frameworks
- Adoption & Maturity Playbook (planned) — Step-by-step organizational change management, stakeholder engagement, pilot selection criteria, and capability assessment tools
Note: Current documents reference these as "planned companion documents." The Core Specification provides a security considerations summary, and the Implementation Guide includes pattern-specific safety considerations as interim guidance.
Read: Whitepaper
Time: 30-45 minutes
You'll Learn:
- What the Dual-Native Pattern is (and isn't)
- Why it matters now (AI as content consumer)
- Real-world evidence (TCT case study with 83% bandwidth savings)
- When to use (and when NOT to use)
- Business value and ROI
Best For: CTOs, architects, product leads, decision-makers
Read: Core Specification
Time: 1-2 hours
You'll Learn:
- Normative requirements (RFC-2119 language: MUST, SHOULD, MAY)
- Formal definitions (RID, CID, HR, MR, DNC)
- Conformance levels (0-4)
- Architectural invariants
- Security and privacy considerations (summary)
Best For: Standards bodies, compliance teams, deep-architecture reviewers
Read: Implementation Guide
Time: 2-3 hours (skim to your domain)
You'll Learn:
- Domain-specific discovery mechanisms (file systems, databases, MQTT, CoAP, Kafka, S3)
- Pattern-specific safety considerations (HR/MR divergence, poisoning, sync failures)
- Performance optimization strategies
- Testing strategies (semantic equivalence, validator parity, zero-fetch)
- Migration playbooks (Level 0 → Level 4)
Best For: Engineers, platform teams, technical leads
Read: Optional Enhancements Guide
Time: 45 minutes
You'll Learn:
- Integrity digests and signatures for tamper evidence
- Immutability patterns for snapshots and versioning
- Evented synchronization (webhooks, CDC, subscriptions)
- Provenance and lineage tracking
- When to use each enhancement (and when to skip)
- Cost/benefit analysis for each option
Best For: Mature deployments seeking advanced assurance, performance, or governance capabilities
Important: These are optional enhancements, not required for conformance. Implement the core pattern first.
Goal: Understand the core idea without reading full documents.
- Read: Whitepaper § Executive Summary (2 min)
- Read: Whitepaper § The Problem (3 min)
- Read: Whitepaper § Pattern at a Glance (5 min)
- Read: Whitepaper § TCT Case Study (5 min)
Key Takeaway: Every resource has HR (human) and MR (machine) representations, linked bidirectionally with semantic equivalence guarantees. Proven to save 83% bandwidth with 90%+ zero-fetch rates.
- Whitepaper § Executive Summary
- Whitepaper § Why Now
- Whitepaper § Impact and Opportunities
- Whitepaper § Getting Started
Decision Point: "Should we adopt this pattern?" → See When NOT to Use
Decision Point: "How mature are we?" → Assess against Conformance Levels 0-4
- Whitepaper § Pattern at a Glance
- Core Spec § Cross-Domain Core Requirements
- Implementation Guide § Your Domain
- Implementation Guide § Safety Considerations
- Implementation Guide § Testing Strategies
Next Step: Choose pilot domain, implement Level 1 (basic MR)
- Whitepaper § Introduction
- Core Spec § Security Considerations
- Core Spec § Privacy Considerations
- Implementation Guide § Pattern-Specific Safety
Action Items: Review threat models, assess compliance implications (HIPAA, GDPR, etc.)
- Implementation Guide (full read)
- Core Spec § DNC Data Model
- Implementation Guide § Migration Playbooks
Next Step: Choose domain, implement discovery mechanism, add bidirectional links
| Term | Definition | Example |
|---|---|---|
| HR | Human Representation (human-optimized interface) | HTML page, dashboard, PDF |
| MR | Machine Representation (machine-optimized interface) | JSON API, Avro stream, FHIR resource |
| RID | Resource Identity (stable identifier shared by HR and MR) | https://example.com/article/123 |
| CID | Content Identity (version validator, enables zero-fetch) | sha256-abc123..., lsn:0/1A2B3C4D |
| DNC | Dual-Native Catalog (registry of all dual-native resources) | JSON sitemap, SQL table, Kafka topic |
| Zero-Fetch | Skip download when CID matches cached version | 304 Not Modified (0 bytes transferred) |
| Semantic Equivalence | HR and MR represent the same content | Dashboard shows $100, API returns {"price": 100} |
For full glossary: See Whitepaper Appendix A
The pattern is not theoretical—it's deployed in production:
Live Sites (5,700+ URLs):
- bestdemotivationalposters.com
- wellbeing-support.com
- omacedonii.com
- llmpages.org
Measured Results:
- 83% bandwidth savings (18.3 KB HTML → 3.1 KB JSON)
- 90%+ zero-fetch rate (304 Not Modified responses)
- Reduced infrastructure costs (CDN egress, server load)
Example: Whitepaper § TCT Case Study
Many industry platforms already provide dual interfaces (HR + MR), though without formal guarantees:
Case Library — 11+ platform case studies:
- Payments: Stripe Dashboard + REST API
- Developer Tools: GitHub Web UI + GraphQL/REST APIs
- Knowledge Graphs: Wikidata pages + SPARQL endpoint
- Data Platforms: Databricks Workspace + REST API
- E-commerce: Shopify Admin + GraphQL API
- CRM: Salesforce Lightning + REST/Bulk APIs
- IoT: Cisco Meraki Dashboard + Dashboard API
- Open Data: Data.gov portal + CKAN API
- Geospatial: OGC/STAC map viewers + APIs
- And more...
Each case shows current state, pattern gaps, recommended upgrades, and expected benefits. Case studies are tagged with their current conformance level (0-4) and recommended target level—see CORE-SPEC § 6.2 for level definitions.
Organizations adopt through capability stages with clear entry/exit criteria, not fixed timelines:
| Stage | Name | Key Exit Criteria | Example KPIs |
|---|---|---|---|
| 1 | Linked Interfaces | HR ↔ MR links resolvable, RID defined, index entry exists | Coverage: 100% of pilot resources |
| 2 | Basic Sync | CID exposed, index includes cid + updatedAt, first skip-fetch observed |
CID Coverage: 100%, Skip Rate: >0% |
| 3 | Optimized Delivery | Skip-rate ≥70% (stable content), drift checks pass, incremental discovery works | Skip Rate: ≥70%, Bandwidth Saved: ≥50% |
| 4 | Adaptive MR | Profiles documented, cost/latency budgets enforced, governance dashboards operational | Profile Adoption: >50%, Cache Hit: >80% |
Goal: Stage 3 is recommended for most systems. Stage 4 is best-in-class.
Details: Whitepaper § Adoption Path: Stage-Based Progression
HTTP Profile:
- TCT Internet-Draft (draft-jurkovikj-collab-tunnel)
- Formal HTTP specification for C-URL/M-URL, M-Sitemap, ETags
Other Domains:
- Databases: See Implementation Guide § Databases
- Streaming: See Implementation Guide § Kafka/Pulsar
- IoT: See Implementation Guide § MQTT/CoAP
- Cloud Storage: See Implementation Guide § S3/Azure/GCS
A: They can (using LLMs or custom parsers), but it's expensive and brittle:
- Parsing 100KB HTML with an LLM costs ~$0.10-$0.50 per request
- HTML structure changes break parsers
- 60-90% bandwidth wasted on navigation, ads, styling
Dual-native design provides clean, structured data that's smaller and doesn't require parsing.
A: No. Most APIs:
- Are separate from human content (no bidirectional discovery)
- Lack semantic equivalence guarantees (drift is common)
- Aren't optimized for AI (missing ETags, catalogs, zero-fetch)
The pattern adds explicit linking, semantic equivalence, and standardized discovery.
A: No. TCT is the HTTP-specific profile. The pattern applies to databases, streaming, IoT, and other domains using their native mechanisms (not HTTP headers).
A: Zero-fetch optimization doesn't help for real-time streams (CID always changes). But dual-native design still benefits:
- MR is more efficient than parsing HR (smaller, structured)
- Bidirectional linking enables discovery
- Semantic equivalence prevents drift
This is a community-driven effort. Contributions welcome:
- Feedback: Open issues for clarifications, corrections, suggestions
- Implementations: Share domain-specific guides (e.g., "Dual-Native for PostgreSQL")
- Case Studies: Document your deployment experiences
- Code Examples: Contribute reference implementations
Repository: https://github.com/antunjurkovic-collab/dual-native-pattern
All documents in this suite are licensed under:
Creative Commons Attribution 4.0 International (CC BY 4.0)
You are free to:
- Share: Copy and redistribute in any medium or format
- Adapt: Remix, transform, and build upon the material
Under the following terms:
- Attribution: Give appropriate credit, provide a link to the license
Full License: https://creativecommons.org/licenses/by/4.0/
Author: Antun Jurkovikj
Contributors:
- IETF HTTP Working Group (TCT feedback)
- W3C Community (Linked Data, Semantic Web)
- Early adopters and production deployers
Special Thanks:
- Open-source contributors to TCT reference implementations
- AI and web standards communities for ongoing dialogue
We Welcome Feedback! This is a community-driven effort in active development. Your input helps refine the pattern and improve the documentation.
How to Provide Feedback:
- GitHub Issues: https://github.com/antunjurkovic-collab/dual-native-pattern/issues — Bug reports, clarifications, suggestions
- Discussions: https://github.com/antunjurkovic-collab/dual-native-pattern/discussions — Questions, use cases, implementation experiences
- Email: antunjurkovic@gmail.com — Direct contact for private inquiries
What We're Looking For:
- Real-world implementation experiences (successes and challenges)
- Domain-specific guidance contributions (e.g., "Dual-Native for PostgreSQL")
- Case study additions documenting your platform
- Clarifications on confusing sections
- Corrections or updates to examples
Questions?
- Read the FAQ
- Check the Whitepaper for context
- Review the Implementation Guide for technical details
Technical Support:
- See "Feedback and Contributions" above for reporting issues
- Check CHANGELOG.md for recent updates and known issues
| Document | Version | Last Updated | Status |
|---|---|---|---|
| README.md | 1.3 | November 2025 | Draft |
| WHITEPAPER.md | 1.3 | November 2025 | Draft for Review |
| CORE-SPEC.md | 1.3 | November 2025 | Draft for Review |
| IMPLEMENTATION-GUIDE.md | 1.3 | November 2025 | Draft for Review |
Versioning: All documents will be versioned together. Updates to any document will increment the suite version.
Last Updated: November 2025 Document Suite Version: 1.3 Status: Draft for Review
Start Reading: Whitepaper →