# AIEP Developer Guide

# Developers

AIEP is open. You can adopt it today.

## The quickest way to contribute

1. Publish `/.well-known/aiep/` on a website you control
2. Add one meaningful artefact with evidence behind it
3. Publish or reference a schema where useful
4. Share your Mirror endpoint so others can retrieve from it

## Why developers should care

AIEP supports a future where:

- information retrieval becomes evidence-backed knowledge retrieval
- AI systems rely on source-published artefacts, not scraped guesses
- developers can build new vertical products on a shared knowledge layer

## Call to arms

**Developers — decentralise knowledge. Disseminate it. Build with AIEP.**

## Standards, not lock-in

AIEP is designed to be adopted incrementally without proprietary lock-in.

See:
- `/mirror-adoption`
- `/.well-known/aiep/`

---

# Developer Quickstart

If you want to adopt AIEP quickly, start small. The goal is to publish a Mirror interface that an automated system can discover and interpret.

## Step 1: Create the well-known directory

Create:

`/.well-known/aiep/`

## Step 2: Publish the two core files

Publish:
- `index.json`
- `metadata.json`

You can copy the structure of this Hub and edit the publisher fields.

## Step 3: Publish your first artefact

Pick a claim that matters and publish an artefact that links the instruction to evidence. Keep it simple. The goal is to prove the pattern.

## Step 4: Add a schema (optional but recommended)

If you want deterministic validation, publish a JSON schema and reference it from your indexes.

## Step 5: Share your endpoint

The ecosystem grows through dissemination. Share your well-known interface URL so others can retrieve from it.

AIEP is open. **Open use is always permitted.**

---

# Mirror Implementation

AIEP Mirror is deliberately simple so adoption can spread without friction. The goal is not to create a complicated framework. The goal is to make a predictable machine interface available on the open web.

## What you publish

A Mirror node publishes a small set of endpoints under:

`/.well-known/aiep/`

At minimum, publish:

- `index.json` — a map of surfaces
- `metadata.json` — publisher identity and declarations

From there, you can publish as much or as little as you need:

- schemas for deterministic validation
- indexes that list artefacts
- ledgers that record concept provenance
- compliance signals if you claim certification

## Why this is enough

Once the machine endpoints exist, AI systems and tools can discover:
- what artefacts you publish
- how to validate them
- which policies apply
- where new information appears

This replaces “scrape and guess” with “retrieve and verify”.

## Stability and versioning

A Mirror node becomes valuable when it stays stable. Version schemas and policy documents. Avoid breaking changes. Publish new versions rather than mutating old ones.

## What this Hub demonstrates

This Hub is a reference implementation in the simplest possible form:
- static endpoints under `/.well-known/aiep/`
- downloadable artefacts under `/downloads/`
- long-form explanation pages for humans

You can replicate it on any domain.

---

# AI Retrieval

AIEP exists because AI systems are increasingly used to find information. Search is being replaced by conversation. But conversation is only safe when it can anchor itself to reliable knowledge.

AIEP enables a new pattern: **evidence-backed knowledge retrieval**.

## What retrieval means in AIEP

An AI system does not start by ranking pages. It starts by discovering a publisher’s machine interface. It retrieves artefacts from the source, then validates structure, integrity, and policy signals.

A typical AIEP retrieval sequence looks like this:

1. Discover `/.well-known/aiep/index.json`  
2. Read `/.well-known/aiep/metadata.json`  
3. Follow surfaces to indexes, schemas, ledgers, and artefacts  
4. Validate artefacts against schemas  
5. Check hashes where available  
6. Separate consensus from outliers  
7. Synthesise an answer with evidence references

## Why this improves safety

The core risk with AI retrieval today is that models improvise around missing ground truth. AIEP reduces that risk by giving models a predictable way to retrieve supporting artefacts from publishers who choose to publish them.

AIEP does not remove judgment. It improves the quality of what judgment is based on.

## Dissent and plausibility

AIEP treats dissent as a structural feature. Retrieval can intentionally surface:
- the consensus view
- competing interpretations
- outliers and radical outliers

This supports scientific discovery and prevents premature collapse into a single narrative.

## The goal

AIEP aims to make it normal for AI systems to rely on published evidence rather than probabilistic guesswork.

**The future of information retrieval is not search — it is evidence-backed knowledge retrieval.**

---

# Deployment (Cloudflare Pages + optional Worker)

This repo is an Astro static site designed for Cloudflare Pages.

## Local run

```bash
npm install
npm run dev
```

## Cloudflare Pages settings

- **Framework preset:** Astro
- **Build command:** `npm run build`
- **Build output directory:** `dist`
- **Node version:** 20 (recommended)

Astro serves everything under `public/` as static assets, including:

- `/.well-known/aiep/*` (machine interface)
- `/downloads/*` (public downloads)

## Optional: NDA-gated downloads + evidential logging

Restricted packs (if/when used) are designed to be served via:

`/dl/nda/<file_id>`

This requires a Cloudflare Worker (or Pages Functions) plus storage bindings
(KV/R2/Durable Objects) for event logging.

In this repo:
- Worker stubs live in `workers/`

## Contact

For operational issues, contact: aiep@phatfella.com

---

# Deployment Worker Plan (NDA downloads + evidential logging)

This plan describes how to implement **restricted NDA-gated downloads** and **tamper-evident event logging** for the AIEP Hub on Cloudflare.

It is designed to preserve your stated principles:

- **Open use is always permitted** (public docs remain frictionless)
- **Restricted packs** (if used) require NDA acceptance
- **Evidential download logs** are recorded for legal purposes
- **VPN/proxy/anonymised networks are blocked only for restricted downloads**
- Governing law: **England & Wales**

---

## 1) Architecture overview

### Cloudflare Pages (static)
Serves:
- Astro site (`/`)
- public downloads (`/downloads/*`)
- machine interface (`/.well-known/aiep/*`)

### Cloudflare Worker (restricted route)
Serves:
- `/dl/nda/*` (restricted downloads only)
- `/api/events/*` (optional: read-only counters)
- `/api/validator/*` (optional: server-side validator)

### Durable Object (tamper-evident event chain)
Stores:
- append-only event entries
- previous hash pointer
- current head hash

### R2 (restricted file storage)
Stores:
- NDA-gated ZIP/PDF/MD packs (private)
- optionally: audit bundles

### KV (lightweight indexes / counters)
Stores:
- download counter aggregates (optional)
- NDA acceptance receipts (optional)

---

## 2) Route table

### Public (Pages)
- `/*` (Astro routes)
- `/.well-known/aiep/*`
- `/downloads/*`

### Restricted (Worker)
- `/dl/nda/:file_id`  → NDA gate + serve from R2
- `/api/counters`      → return human/ai counters (optional)
- `/api/events/:id`    → fetch event record (optional, restricted)

---

## 3) Restricted download flow (NDA gate)

### Step A — Request
User requests:
`GET /dl/nda/<file_id>`

Worker checks:
1. **File exists** in R2 (or manifest)
2. **NDA acceptance**:
   - If not accepted → show HTML NDA page with “Accept” button
3. **VPN/proxy restriction** (restricted only):
   - If request appears to be from VPN/proxy/anonymised network → deny (403)
4. **Evidential log**:
   - append event to Durable Object chain
5. **Serve file**:
   - stream from R2 with correct content-type and content-disposition

### Step B — Acceptance
User submits:
`POST /dl/nda/<file_id>/accept`

Worker records:
- timestamp (UTC)
- file_id requested
- NDA version identifier (e.g. `AIEP_DEVELOPMENT_NDA_v1`)
- acceptance hash

Then sets:
- `Set-Cookie: aiep_nda_accept=<signed_token>; Secure; HttpOnly; SameSite=Lax`

Token contains (signed):
- accepted_at_utc
- nda_version
- optional: anonymised fingerprint (minimal)
- optional: expiry (e.g. 90 days)

Acceptance is **not** a replacement for a wet signature; it is an evidential acknowledgement for download gating.

---

## 4) VPN / proxy detection (restricted only)

Cloudflare Workers expose `request.cf` fields and IP info.

Recommended approach (pragmatic):
- block **known** proxy/VPN ASN ranges using a maintained list (stored in KV)
- optionally block if:
  - `request.cf.botManagement.score` below threshold (if Bot Management enabled)
  - `request.cf.asn` matches known VPN providers
  - `request.cf.threatScore` above threshold (if available)

Important: this is inherently imperfect. The purpose is *evidential integrity*, not absolute prevention.

---

## 5) Evidential event log (Durable Object)

### Data model (append-only)
Each event includes:
- `event_id` (uuid or monotonic id)
- `timestamp_utc`
- `event_type` (`NDA_ACCEPTED`, `RESTRICTED_DOWNLOAD_SERVED`, `RESTRICTED_DOWNLOAD_DENIED`)
- `file_id`
- `request_ip_hash` (hash of IP with salt; do not store raw IP unless you must)
- `user_agent_hash`
- `prev_hash`
- `event_hash` (hash of canonical JSON + prev_hash)

This forms a hash chain:
`H(n) = SHA256( canonical_event(n) + H(n-1) )`

Store:
- head hash
- events by id
- optional daily checkpoints

### Legal notes
- Keep timestamps in UTC
- Keep canonical JSON stable (field ordering)
- Keep salts stable but secret (environment secret)

---

## 6) Restricted file manifest (recommended)

Create:
`workers/restricted_manifest.json`

Example:
```json
{
  "nda_version": "AIEP_DEVELOPMENT_NDA_v1",
  "files": {
    "forecast-pack": {
      "r2_key": "restricted/forecast/forecast-pack.zip",
      "filename": "Forecast_Pack.zip",
      "content_type": "application/zip"
    }
  }
}
```

This makes `file_id` stable and reviewable.

---

## 7) Counters (human views + AI crawls)

Two ways:

### Option A (simple, honest)
Use real analytics later. Until then, display “demo” counters (already implemented).

### Option B (Worker-backed)
- `GET /api/counters` returns JSON counters
- increment in Worker on:
  - page views (requires Pages Function or JS beacon)
  - AI crawls (based on user-agent heuristics + rate limits)

Store aggregated counters in KV:
- `counter:human:YYYY-MM-DD`
- `counter:ai:YYYY-MM-DD`

Expose only totals publicly.

---

## 8) Implementation skeleton

Create files:
- `workers/nda-download-worker.js`
- `workers/event-chain-do.js`
- `workers/restricted_manifest.json`

Bindings (wrangler.toml concept):
- R2: `AIEP_RESTRICTED`
- KV: `AIEP_KV`
- DO: `AIEP_EVENT_CHAIN`

---

## 9) Publishing discipline

- Public docs are always in `/downloads/*`
- Restricted packs are never committed to the public repo
- Restricted packs live in R2 only
- Public ledger entries may include sealed hashes of restricted packs

---

## 10) Checklist before going live

- [ ] NDA page is correct and versioned
- [ ] DO hash chaining verified with a test suite
- [ ] VPN/proxy restrictions apply only to `/dl/nda/*`
- [ ] Public downloads remain accessible via VPN
- [ ] Contact email is set
- [ ] Governing law statements are present (England & Wales)