# AIEP Hub Architecture Map Version 1.0 Author: Neil Grassby Protocol: Architected Instruction & Evidence Protocol (AIEP) --- ## Purpose The AIEP Hub serves as the public entry point to the AIEP ecosystem. It provides: - human-readable explanations of the protocol - machine-readable endpoints for discovery - documentation and downloads - governance and certification information - participation pathways for developers, academia, and partners The Hub is designed to be **static-first**, published via GitHub and served globally via Cloudflare. --- ## Core Principle **AIEP is an open protocol. Open use is always permitted.** The Hub encourages adoption while maintaining safeguards for: - truthful certification claims - confidential development materials (NDA-gated) - evidential download logging for restricted materials --- ## Human-Facing Site Map ### Core - `/` — Home (hero + ecosystem overview) - `/vision` — Plain English vision (dissent/outliers, jigsaw model, “knowledge grows when shared”) - `/architecture` — Architecture of Knowing + protocol overview - `/spec` — Specification index (versioned) - `/glossary` — Terms (artefact, mirror, node, validator, registry, certification, etc.) - `/security` — Security considerations - `/misconceptions` — “AIEP is not…” clarifications - `/roadmap` — Phased roadmap ### Mirror - `/mirror` — What Mirror is - `/mirror-adoption` — “Become a Mirror node” (simple adoption path) ### Participation - `/developers` — Developer entry point - `/builders` — Builder Programme (Qardl + Forecast as first verticals; NDA required; “up to 10%” model; edu routing) - `/academia` — Academic programme (free to explore; commercialisation later) - `/academia/builder-challenge` — Student Builder Challenge ### Innovation Ledger - `/innovation-ledger` — Public ledger list + per-entry pages - `PUBLIC` entries show full body - `NDA` entries show public summary + sealed hash + “request access” pathway ### Trust, certification, compliance - `/certification` — Open use permitted; certification only protects the claim “AIEP Certified” - `/compliance` — Compliance scope (false certification + NDA leakage only) - `/compliance/trawler` — Trawler description + reporting ### Downloads - `/downloads` — Downloads index (Public vs Restricted) - `/downloads/docs` — Public `.md` - `/downloads/white-papers` — Public `.pdf` - `/downloads/repos` — Public `.zip` - `/downloads/schemas` — Public `.json` - `/downloads/legal` — Legal `.md` (NDA + access policy) - `/downloads/access-policy` — VPN restriction scope (restricted only) ### Contact - `/licensing` — Protocol open-use statement + certification mark wording - `/contact` — Contact and reporting channel - `/feedback` — Feedback page (optional) - Footer (optional): small counters (human views + AI trawls) and “Machine interface at `/.well-known/aiep/`”. --- ## Machine Interface Map (Canonical) All machine endpoints live under: `/.well-known/aiep/` ### Required - `/.well-known/aiep/index.json` — Hub machine index (links to machine surfaces) - `/.well-known/aiep/metadata.json` — Hub metadata incl. open-use policy + certification claim rules - `/.well-known/aiep/schemas/` — public schemas (incl. metadata + ledger schemas) - `/.well-known/aiep/canon/` — canon docs (open use + certification rules) ### Innovation Ledger (machine + content) - `/.well-known/aiep/innovation-ledger/index.json` — machine list of entries - `/.well-known/aiep/innovation-ledger/entries/` — `AIEP-LEDGER-######.md` - `/.well-known/aiep/innovation-ledger/schema/aiep.innovation_ledger_entry.schema.v1.json` ### Downloads (optional but recommended) - `/.well-known/aiep/downloads/index.json` — lists public download artefacts and hashes ### Compliance (machine) - `/.well-known/aiep/compliance/policy.json` — scope: false certification + NDA leakage only - `/.well-known/aiep/compliance/signals.json` — required fields for certification claims ### Certificates (issuer-controlled; may be external to hub) - `/.well-known/aiep/certificates/.json` — certificate artefact + signature --- ## Restricted Downloads + NDA Gate (Cloudflare Worker) Public downloads remain static to avoid frustration. ### Public (no VPN restrictions) - `/downloads/docs/*` - `/downloads/white-papers/*` - `/downloads/repos/*` - `/downloads/schemas/*` ### Restricted (NDA + VPN restricted + event logged) - `/dl/nda/` — Worker only - NDA acceptance required - VPN/proxy/anonymized networks blocked - event log generated (tamper-evident chain) - file served (from R2/private storage) --- ## Event Logging (Restricted downloads only) Purpose: evidential download records for legal purposes. ### Event types - `NDA_ACCEPTED` - `DOWNLOAD_REQUESTED` - `DOWNLOAD_SERVED` - `DOWNLOAD_DENIED_VPN` - `DOWNLOAD_DENIED_POLICY` - `PARTNER_APPLICATION_SUBMITTED` (optional future) - `PACK_HASH_PUBLISHED` (for sealed hash entries) ### Rule No restricted download is served unless an event is logged first. ### Integrity Append-only hash chain (`chain_prev`, `chain_curr`) to make tampering evident. --- ## Certification + Compliance Logic ### Open use Anyone can implement AIEP/Mirror. No enforcement against adoption. ### Compliance scope Only: - false “AIEP Certified” claims - misuse of certification mark/phrase - NDA pack leakage (where applicable) ### Fail-closed certification claim If `claims_aiep_certified=true` in `/.well-known/aiep/metadata.json`, then: - `certificate_id`, `certificate_url`, `issuer`, `issuer_public_key`, `signature` MUST exist - signature must validate against issuer key Otherwise the certification claim is invalid. --- ## Publishing Rule **New idea = add one markdown file** to: `/.well-known/aiep/innovation-ledger/entries/` Commit + deploy publishes it and establishes timestamp provenance. --- ## Builder Programme First two verticals: - **Qardl** - **Forecast** Participation: - “up to 10%” in the vertical, subject to proof and contract - revenue not guaranteed - NDA required for detailed materials Education routing: - where developed via an educational institution, allocation may be routed to the institution (subject to agreement). --- ## Mirror contribution (partner participation) Partners are encouraged to enable Mirror endpoints across websites/apps they manage, as part of meaningful ecosystem participation. --- ## Deployment - Source on GitHub - Published via Cloudflare Pages - Machine interface under `/.well-known/aiep/` --- ## Governance principle **Open adoption, verifiable certification.** The protocol is open. Certification claims must be truthful.