e95c978481
This commit implements Phase 17 of the Aphoria roadmap, adding: **Inline Claim Markers (@aphoria:claim):** - New extractor for detecting inline markers in comments - Pending markers tracked in .aphoria/pending_markers.toml - CLI commands: list-markers, formalize-marker, reject-marker - Support for all major comment styles (Rust, Python, SQL, etc.) - Auto-sync during scan (configurable) **Claim Enrichment:** - ClaimEnrichment type with source attribution (inline, extractor, manual) - EnrichedClaimInfo with full enrichment metadata - Extended AuthoredClaim with optional enrichment field - API endpoints for enriched claim queries - Dashboard UI components (enrichment badge, verdict badge) **Enhanced Extractor Trait:** - verifiable_predicates() method for declaring (tail_path, predicate) pairs - 10 security extractors now implement verifiable_predicates - Enables claim suggester skill to find unclaimed patterns **Documentation:** - Phase 17 summary with complete implementation details - Gap fixes summary documenting 8 closed vision gaps - Updated CLI reference with new commands - New aphoria-docs skill for documentation maintenance - Updated roadmap with Phase 17 completion **Integration:** - ClaimsFile support for claim enrichment persistence - Pattern aggregate store support for enrichment queries - Dashboard filters and display for enrichment metadata - API handlers for list-markers and enrichment queries **Tests:** - New gap_fixes_integration test suite - Corpus enricher module with best practices ingestion Closes: VG-005, VG-017, VG-018, VG-019, VG-020, VG-021, VG-022, VG-023 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.**
|