# Proposal: Aphoria Federated Policy & Trust Packs

**Date:** 2026-02-03
**Feature:** Federated Knowledge Network
**Status:** PROPOSAL
**Target Version:** Aphoria 0.2.0

---

> **Implementation status:**
> - **Trust Pack export/import** -- Implemented and working. Ed25519 signed bundles can be exported from one project and imported into another. Signature verification works.
> - **Live federation** -- Not implemented. There is no remote policy resolution (`policy://` URIs), no org-wide server, and no automatic cross-repo sync. The `policy://` scheme described below is a design proposal only.
> - **Community Pack** -- Not implemented. No published community packs exist.

## Executive Summary

The VulnBank demo proved that Aphoria is a superior **Single-Player Linter** (100% precision vs 20% for pattern matchers). To achieve the StemeDB vision of a "Probabilistic Marketplace," Aphoria must evolve into a **Multiplayer Knowledge Network**.

This proposal outlines the **Federated Policy** architecture, allowing organizations to export their "truth" (acknowledgments, aliases, and custom assertions) as portable **Trust Packs**. This turns StemeDB from a local backing store into a competitive moat where network effects compound.

---

## The Problem: Truth is Trapped

Currently, when a Security Engineer runs `aphoria ack` to allow MD5 for file hashing (but not auth), that knowledge is trapped on their laptop or in their specific project's `.aphoria/db`.

1.  **Organizational Amnesia:** Another team starts a new project and hits the same MD5 conflict. They have to re-adjudicate it.
2.  **Stale Compliance:** Security policies update, but developer laptops have stale local corpora.
3.  **Zero-Sum Game:** Every user starts from zero. There is no "community knowledge" benefit to using Aphoria.

**The "Show Stopper" Gap:**
Enterprise customers will ask: *"How do I enforce my security team's specific deviations across 500 repos without copy-pasting config files?"*

---

## The Solution: Trust Packs

A **Trust Pack** is a cryptographically signed bundle of assertions, aliases, and acknowledgments that can be subscribed to via a URI.

### New Concept: `policy://`

We introduce a new scheme for identifying policies:

```
policy://github.com/acme-corp/security-standards
policy://stemedb.com/rust-community/web-defaults
```

### Workflow

**1. The Security Team (Producers)**
They scan a reference repo, adjudicate conflicts, and export their decisions:

```bash
# Security engineer approves MD5 for non-crypto use
$ aphoria ack "code://rust/legacy-app/crypto/hashing/algorithm" --reason "File integrity only"

# Export the policy
$ aphoria policy export --name "Acme Legacy Compat" --out ./acme-legacy.pack
```

**2. The Feature Team (Consumers)**
They subscribe to the policy in `aphoria.toml`:

```toml
[policies]
base = "policy://stemedb.com/rust-standard"
security = "policy://internal/acme-legacy.pack"
```

**3. The Enforcement (Runtime)**
When the feature team runs `aphoria scan`, the engine:
1. Loads the authoritative corpus (RFCs)
2. Overlays the `rust-standard` pack (Community norms)
3. Overlays the `acme-legacy` pack (Internal overrides)
4. Checks conflicts against this *composite* truth

If the feature team tries to use MD5 for *password hashing*, it BLOCKS (violates RFC).
If they use it for *file integrity*, it PASSES (allowed by Acme Legacy).

---

## Architecture Changes

### 1. Policy Export Format
A Trust Pack is a serialized, compressed export of a StemeDB graph subset, signed by the author's Agent Key.

```rust
struct TrustPack {
    header: PackHeader, // Name, Version, Issuer PubKey
    assertions: Vec<Assertion>, // The 'ack' claims
    aliases: Vec<Alias>, // "my-lib/config" -> "rfc/config"
    signature: Signature, // Proof of provenance
}
```

### 2. TrustRank Integration
StemeDB's `TrustRank` becomes the conflict resolver.

*   **RFC (Tier 0)**: Weight 1.0
*   **Security Team Policy (Tier 3)**: Weight 0.8 (can override Tier 4/5, contextually override Tier 1/2 via "Skeptic" lens allow-lists)
*   **Local Developer (Tier 5)**: Weight 0.1

### 3. Remote Resolution
Support fetching policies over HTTP/Git:

```rust
// In aphoria.toml
policies = [
    "https://policies.acme.corp/v1/backend.pack",
    "git+ssh://git@github.com/acme/security.git//policies/core.pack"
]
```

---

## Implementation Roadmap

### Phase 1: Local Export/Import
- [ ] `aphoria policy export` command
- [ ] `aphoria policy import <file>` command
- [ ] Schema definition for `TrustPack` (using `rkyv` for zero-copy speed)

### Phase 2: Remote Resolution
- [ ] URL support in `aphoria.toml` policy list
- [ ] Caching layer in `~/.cache/aphoria/policies/`
- [ ] Signature verification on import

### Phase 3: The "Community Pack"
- [ ] Publish an official "Real World Rust" pack that reduces noise from common, safe patterns in popular crates (reqwest, tokio, etc.)
- [ ] Demonstrate "Zero Config" scans for open source projects

---

## Success Criteria (The "Enterprise Grade" Bar)

1.  **Portability:** Can I email a policy file to a colleague and have their scan results match mine exactly?
2.  **Inheritance:** Can I define a "Base Policy" and have "Service A Policy" inherit from it?
3.  **Traceability:** When a scan passes because of a policy override, does the report say *"Allowed by Policy: Acme Security (signed by @alice)"*?

**Verdict:**
This moves Aphoria from a tool that *finds* bugs to a platform that *distributes* knowledge. This is the StemeDB vision realizing its potential.