jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cde30b9213
stemedb/applications/aphoria/docs/advanced/eap-protocol.md
jordan 422e2d4416 feat(aphoria): wire claims through StemeDB — Gap Closure Phase 1 
Claims now flow through StemeDB's append-only knowledge graph instead of
mutable TOML files. This resolves all 6 critical claim-bypass code paths:

- Bridge: lossless AuthoredClaim ↔ Assertion round-trip (comparison, status, lifecycle mapping)
- LocalEpisteme: ingest_authored_claim() and fetch_authored_claims() with AUTHORED_CLAIM predicate index
- EpistemeClaimStore: ClaimStore trait backed by StemeDB (append-only delete via deprecation)
- CLI handlers: all claim commands read/write through StemeDB
- Scanner: loads claims from StemeDB with auto-migration fallback to TOML
- Export: new `aphoria claims export` serializes StemeDB claims to TOML/JSON

Also cleans up dead code (EpistemeConfig.url), renames ingest_claims→ingest_observations,
fixes ClaimFilter.authority_tier type, adds Draft variant to ClaimStatus, and fixes
pre-existing clippy warnings (too_many_arguments, filter_next→rfind).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 02:02:51 -07:00

4.7 KiB
Raw Blame History

The Open Vision: The Epistemic Assertion Protocol (EAP)

STATUS: ASPIRATIONAL / PLANNED -- Nothing described in this document is implemented. There is no EAP protocol, no manifest format, no "DNS for Truth" server, and no global ingestion network. This is a long-term vision document. For what Aphoria does today, see the CLI Reference and Aphoria README.

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.

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.