9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# The Open Vision: The Epistemic Assertion Protocol (EAP)
|
|
|
|
> **Protocol Vision:** This document describes the Epistemic Assertion Protocol (EAP) - an open standard for publishing authoritative technical knowledge. For Aphoria's product vision, see [Vision](vision.md).
|
|
|
|
**From "Reading the Manual" to "Querying the Truth."**
|
|
|
|
## The Stagnation of Truth
|
|
For 40 years, the authoritative "Truth" of software engineering has been locked in dead formats:
|
|
* **RFCs** are ASCII text files.
|
|
* **OWASP Standards** are Markdown wikis.
|
|
* **Vendor Recommendations** are HTML documentation portals.
|
|
|
|
These formats are designed for **Human Consumption**. But humans are no longer the only ones writing code.
|
|
|
|
AI Agents cannot "read" an RFC and "understand" the nuance of a `SHOULD` vs. a `MUST` reliably enough for safety-critical systems. They need structured data. They need a protocol.
|
|
|
|
## The Proposal: A Universal Standard for Truth
|
|
We propose the **Epistemic Assertion Protocol (EAP)**: an open standard for publishing authoritative technical knowledge as graph-ready assertions.
|
|
|
|
Aphoria is not just a linter; it is the **Reference Implementation (Browser)** for this new web of data.
|
|
|
|
### 1. The Protocol Layers
|
|
|
|
#### Layer 1: Truth Publishing (The Supply Side)
|
|
Instead of just publishing a PDF, standards bodies and vendors publish an **EAP Manifest**.
|
|
|
|
* **The IETF** publishes `rfc7519.eap.json`: Machine-readable definitions of JWT claims, mandatory validations, and algorithmic constraints.
|
|
* **AWS** publishes `rds-postgres.eap.json`: Recommended connection pool sizes, timeout settings, and SSL modes, versioned by engine release.
|
|
* **Corporate Security** publishes `corp-policy.eap.json`: Internal overrides for encryption standards.
|
|
|
|
**The Win:** Vendors stop writing "Best Practices" guides that nobody reads. They publish "Best Practices" data that tools automatically enforce.
|
|
|
|
#### Layer 2: Semantic Mapping (The Bridge)
|
|
The protocol defines a universal namespace for software concepts (`ConceptPaths`).
|
|
* `concept://net/tls/verification`
|
|
* `concept://auth/jwt/audience`
|
|
* `concept://db/connection/timeout`
|
|
|
|
This allows a Rust extractor, a Go extractor, and a Python extractor to all map their specific implementation details to the *same* universal concept.
|
|
|
|
#### Layer 3: The Consumption Engine (The Demand Side)
|
|
Any tool can consume EAP data.
|
|
* **IDEs** can highlight a config value and say: *"AWS recommends 30s here (Tier 2 Authority)."*
|
|
* **CI Pipelines** can block merges based on Policy.
|
|
* **AI Agents** can query the protocol *before* writing code: *"What is the mandatory TLS version for this service type?"*
|
|
|
|
## Why This Wins (The Strategy)
|
|
|
|
### 1. The "Wikipedia" Effect
|
|
If we try to ingest the world's knowledge ourselves, we lose. If we provide the *standard format* for knowledge, the world does the work for us.
|
|
* **Phase 1 (Aphoria):** We scrape and ingest (current state).
|
|
* **Phase 2 (Community):** Open Source maintainers contribute EAP definitions for their libraries to stop users from misconfiguring them.
|
|
* **Phase 3 (Standard):** "EAP Compatible" becomes a requirement for enterprise adoption of new libraries.
|
|
|
|
### 2. The Agentic Moat
|
|
AI Agents fundamentally change the market.
|
|
* **Old World:** Developers read docs.
|
|
* **New World:** Agents query APIs.
|
|
There is currently **NO API** for "Is this architectural decision correct?"
|
|
Aphoria + EAP becomes that API. We become the **DNS for Truth**.
|
|
|
|
### 3. Commoditizing the Linter, Monopolizing the Graph
|
|
Traditional linters (ESLint, Pylint) are commodities.
|
|
By making the *assertions* an open standard, we encourage widespread adoption.
|
|
However, **StemeDB** (the engine that efficiently stores, versions, and resolves conflicts in this massive graph) remains the high-performance proprietary/core engine required to run this at scale.
|
|
|
|
## The Future Workflow
|
|
|
|
1. **Vendor Release:** Redis releases v8.0. They publish `redis-v8.eap` detailing new timeout behaviors.
|
|
2. **Global Ingest:** The global Aphoria network ingests this update.
|
|
3. **Local Alert:** 10,000 developers (and 50,000 AI agents) wake up to a "Config Drift" warning. Their code hasn't changed, but the *Truth* regarding that code has.
|
|
4. **Auto-Remediation:** The Agent sees the conflict, reads the EAP recommendation, and opens a PR to update the config.
|
|
|
|
**Aphoria is not just finding bugs. It is synchronizing the state of the world's code with the state of the world's knowledge.**
|