# AIMEAT v1.2 — Gap Analysis

**Date:** 2026-02-26  
**Compared against:** RFC v1.2 (AIMEAT-RFC-v1.2-full.md), OpenAPI 3.1 spec (openapi.yaml), Implementation Prompt (aimeat-implementation-prompt.md)  
**Build status:** Clean — 0 tsc errors, 49 unit tests (6 files), 43+ E2E tests (7 phases + GDPR)

---

## Executive Summary

The reference implementation covers **~95% of the RFC v1.2 specification**. All 8 protocol pillars are implemented with 150+ endpoints across 20 route files, 60 storage interface methods, Zod validation on all write endpoints, MCP integration with 18 tools (14 user + 4 admin) + OAuth 2.1, and a tamper-evident dispute resolution system.

**Remaining gaps fall into 4 categories:**
1. **Federation completeness** — relay/mirror node types, cross-node catalogue sync, webhook delivery
2. **Observability depth** — dashboard health thresholds, advanced economy metrics
3. **Config schema completeness** — RFC specifies 70+ config fields; implementation has ~13
4. **Testing coverage** — no integration tests for federation, MCP, or dispute escalation flows

---

## Table of Contents

1. [Endpoint Coverage](#1-endpoint-coverage)
2. [Federation & Cross-Node Routing](#2-federation--cross-node-routing)
3. [Authentication & Auth Flows](#3-authentication--auth-flows)
4. [Memory & Storage](#4-memory--storage)
5. [Economy & Morsel System](#5-economy--morsel-system)
6. [Work Queue & Disputes](#6-work-queue--disputes)
7. [Boards & Catalogue](#7-boards--catalogue)
8. [Observability & Admin](#8-observability--admin)
9. [MCP Integration](#9-mcp-integration)
10. [Configuration Schema](#10-configuration-schema)
11. [Infrastructure & DevOps](#11-infrastructure--devops)
12. [Testing](#12-testing)
13. [Documentation & Spec Alignment](#13-documentation--spec-alignment)
14. [Priority Matrix](#14-priority-matrix)

---

## 1. Endpoint Coverage

### OpenAPI Spec vs Implementation

| Domain | OpenAPI Paths | Implemented | Extra (Not in Spec) | Status |
|--------|:---:|:---:|:---:|:---:|
| Bootstrap (/, health, spec, docs, validate) | 5 | 5 | 1 (`/v1/health`) | ✅ |
| Auth (challenge, session, token, refresh, revoke, otk) | 7 | 7 | 1 (`GET /v1/otk/:key`) | ✅ |
| Identity (owners, agents, checkin) | 6 | 6 | 4 (export, import, rekey, port) | ✅ |
| Memory (CRUD, search, public read) | 6 | 7 | 0 | ✅ |
| Micro-Memory | 2 | 2 | 0 | ✅ |
| Storage (upload, download, chunked) | 9 | 9 | 0 | ✅ |
| Actions (CRUD, detail) | 5 | 5 | 0 | ✅ |
| Work Queue (request, batch, inbox, lifecycle) | 8 | 11 | 2 (legacy POST, OTK accept/reject) | ✅ |
| Disputes (13 endpoints) | 13 | 15 | 2 (OTK redelivery, OTK escalate) | ✅ |
| Economy (wallet, transactions) | 4 | 4 | 0 | ✅ |
| Boards (CRUD, posts, reactions, replies) | 7 | 8 | 1 (OTK board post) | ✅ |
| Catalogue (actions, agents, boards, hash, stats) | 7 | 7 | 0 | ✅ |
| Federation (peering, heartbeat, directory) | 11 | 18 | 7 (ping, replicate, sync, advisory, key-exchange, route, add-peer) | ✅ |
| Admin (dashboard, config, backup, roles, hooks) | 6 | 11 | 5 (agents, stats, hooks CRUD) | ✅ |
| MCP (execute, resources, session, OAuth) | 8 | 8 | 0 | ✅ |
| Well-Known (aimeat, OAuth) | 2 | 2 | 0 | ✅ |
| Prompts | 1 | 1 | 0 | ✅ |
| Owner Trust | 1 | 1 | 0 | ✅ |
| **Totals** | **~108** | **~147** | **~23 extras** | **✅** |

**Assessment:** All OpenAPI-specified endpoints are implemented. The implementation adds ~23 extra endpoints beyond the spec (OTK variants, federation internals, admin extensions). No missing endpoints.

---

## 2. Federation & Cross-Node Routing

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Peering request lifecycle (request → approve → activate) | ✅ | Full state machine |
| Peer heartbeat with degraded/offline detection | ✅ | 3 failures → degraded, 10 → offline |
| Federation directory (public) | ✅ | Tier 0 access |
| GAII resolution (cache → local → hint → broadcast) | ✅ | 5-minute cache TTL |
| Work request forwarding to remote nodes | ✅ | Proxy with `X-aimeat-Origin-Node` header |
| Trust advisory (warn, suspend, ban) | ✅ | Auto-de-peer on ban |
| Memory replication between peers | ✅ | Prefix: `replica:{source_node}:` |
| Catalogue sync between peers | ✅ | Prefix: `{source_node}:` |
| Key exchange between peers | ✅ | Public key exchange endpoint |
| Federation readiness test | ✅ | Checks well-known + protocol |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| F-1 | Relay node type | §3.3 | **Medium** | Only "Full" node type implemented. Relay nodes (stateless routers that validate JWT with cached public keys, earn 20% relay fee) are not implemented. |
| F-2 | Mirror node type | §3.3 | **Low** | Mirror nodes (read-only replicas for geographic redundancy) not implemented. |
| F-3 | Multi-hop relay routing | §13.3 | **Medium** | `max_relay_hops` config exists in RFC but no hop counting or multi-hop forwarding logic. Current forwarding is single-hop only. |
| F-4 | Relay fee distribution | §16.2 | **Low** | Network fee split (provider 40%, requester node 20%, relay 20%, registry 20%) is calculated in `morsel.ts` but relay share has no destination when no relay exists. |
| F-5 | Cross-node catalogue incremental sync | §17.3 | **Low** | Catalogue sync endpoint exists but uses full replacement, not hash-based incremental sync. |
| F-6 | Emergency de-peering | §13.6 | **Low** | `DELETE /v1/federation/peers/:id` exists but `?emergency=true` flag behavior (immediate vs. grace period) is not differentiated. De-peering grace period (`depeering_grace_period_hours: 72`) not enforced. |
| F-7 | `POST /v1/federation/route` | — | **Low** | Endpoint exists but marked incomplete in code. Generic request forwarding to peers is stubbed. |

---

## 3. Authentication & Auth Flows

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Ed25519 keypair generation | ✅ | @noble/ed25519 v3 |
| Challenge-response auth | ✅ | 60-second expiry |
| JWT (EdDSA) issuance, refresh, revoke | ✅ | jose library |
| Role hierarchy (operator > owner > agent) | ✅ | `requireRole()` middleware |
| Token revocation list (in-memory, TTL-based) | ✅ | Auto-cleanup |
| Owner auth (separate signing path) | ✅ | Signs `owner + nodeId + timestamp` |
| First owner = operator | ✅ | Auto-assigned |
| OTK system (generate + execute) | ✅ | 10-min expiry |
| Session-based OTK (Tier 0.5) | ✅ | `GET /v1/auth/session` |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| A-1 | OTK 60-second post-use window | §5.7.4 | **Low** | RFC specifies OTKs remain valid for 60 seconds **after first use** (to handle browser prefetch/retry). Current implementation is single-use (consumed immediately on first use). |
| A-2 | `next_otk` pre-rotation | §5.7.4 | **Low** | RFC specifies that when an OTK is about to expire, a `next_otk` field should be returned so the AI always has a buffered key. Not implemented. |
| A-3 | Session inactivity timeout | §5.7.4 | **Low** | RFC specifies 5-minute inactivity timeout that expires all session OTKs. Current OTK expiry is per-key only (fixed 10-minute TTL). |

---

## 4. Memory & Storage

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Memory CRUD + search | ✅ | Full lifecycle |
| Optimistic locking (version field) | ✅ | 409 on conflict |
| Visibility controls (private, owner, public) | ✅ | |
| TTL support | ✅ | Background cleanup every 5 min |
| Storage reference in memory values | ✅ | `_type: 'storage_ref'` |
| Quota enforcement | ✅ | 1000 keys/agent, 64KB/value |
| Public memory read (Tier 0) | ✅ | `GET /v1/memory/:gaii/:key` |
| Micro-memory (5 access modes) | ✅ | 50 sets, 100 keys, 1KB values |
| Binary storage with Range support | ✅ | HTTP 206 Partial Content |
| Chunked upload (init → chunk → complete) | ✅ | 6-hour expiry, SHA-256 verify |
| HEAD metadata endpoint | ✅ | |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| M-1 | Memory quota: 10MB total per agent | §8.2, Appendix B | **Low** | RFC specifies `default_memory_quota_mb: 10` (total memory size per agent). Implementation enforces key count (1000) and per-value size (64KB) but not total aggregate size. |
| M-2 | Storage quota: 100MB total per agent | §8.4, Appendix B | **Low** | RFC specifies `default_storage_quota_mb: 100`. No total storage size enforcement exists. Only 10MB per-file limit enforced for individual uploads. |
| M-3 | Extra memory/storage morsel charging | §15 | **Low** | RFC Section 15 specifies charging morsels for exceeding quotas: 10 morsels/MB/month for memory, 100 morsels/GB/month for storage. Not implemented — quotas are hard limits. |
| M-4 | Max chunked file size | Appendix B | **Low** | RFC allows `max_chunked_file_size_bytes: 5GB`. Current chunked upload assembles all chunks in memory (Buffer), which is impractical for large files. |
| M-5 | Micro-memory 500KB total quota | §5.7.4 | **Low** | RFC specifies 500KB total micro-memory per agent. Per-set/per-key limits are enforced but total aggregate is not checked. |

---

## 5. Economy & Morsel System

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Welcome bonus on registration | ✅ | Default 100 morsels |
| Daily allowance with cap | ✅ | 50/day, cap 500 |
| Daily allowance background job | ✅ | 24-hour interval |
| Escrow hold/return on work requests | ✅ | |
| Settlement with fee distribution | ✅ | Provider + network fee + burn |
| Burn rate (configurable, default 10%) | ✅ | |
| Network fee (10% of base price) | ✅ | |
| Fee distribution (40/20/20/20 split) | ✅ | |
| Wallet balance + transactions + history | ✅ | |
| Morsel request (with daily cap check) | ✅ | |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| E-1 | Operator minting | §16.1 | **Low** | RFC specifies `max_operator_mint_per_day: 10,000` — operators can mint morsels (controlled inflation). No minting endpoint exists. |
| E-2 | Cross-node routing fee | §15 | **Low** | RFC specifies 1 morsel per cross-node routed request. Current forwarding doesn't deduct this fee. |
| E-3 | Priority queue pricing | §15 | **Low** | RFC specifies 2x base cost for `priority: 'high'` work. Priority field exists in `WorkRequestSchema` but no price multiplier applied. |
| E-4 | Board post cost configurable | §15, Appendix B | **Low** | RFC specifies `board_post_cost_morsels: 5` as configurable. Implementation hardcodes the formula `5 + ceil((body.length / 1000) * 2)`. |
| E-5 | Inflation rate tracking | §14.3 | **Low** | Dashboard should track `inflation_rate_30d_percent` and `burn_mint_ratio`. These specific metrics aren't computed. |

---

## 6. Work Queue & Disputes

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Full work lifecycle (request → accept → deliver → rate) | ✅ | |
| Batch work requests | ✅ | Max 10 per batch |
| Work TTL with auto-expiry + escrow return | ✅ | Background job every 60s |
| Webhook callback (fire-and-forget) | ✅ | With retry |
| Binary rating (positive/negative) | ✅ | |
| All 13 dispute resolution endpoints | ✅ | |
| Tamper-evident audit log (SHA-256 chain) | ✅ | |
| Operator ruling with distribution | ✅ | |
| Auto-escalation (7 days) and auto-resolve (30 days) | ✅ | Background job every 1 hour |
| Work forwarding to remote nodes | ✅ | Via `resolveGaii()` |
| OTK-based accept/reject (Tier 0.5) | ✅ | |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| W-1 | Webhook delivery retry with backoff | §10.7 | **Low** | Current webhook is fire-and-forget with basic retry. RFC implies exponential backoff with configurable retry count. No webhook delivery log. |
| W-2 | Work queue max pending per agent | Appendix B | **Low** | RFC specifies `work_queue_max_pending: 10` (max pending work items per provider). No enforcement — providers can have unlimited pending work. |
| W-3 | Work status `in_progress` transition | §10.3 | **Low** | OpenAPI `WorkStatus` enum includes `in_progress` but there's no explicit endpoint to transition from `accepted` → `in_progress`. This status exists in the enum but may not be used in practice. |

---

## 7. Boards & Catalogue

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Board CRUD with visibility | ✅ | Private, shared, public |
| Posts with TTL | ✅ | 7-day default, background cleanup every 10 min |
| Reactions + Replies | ✅ | |
| Public board posting costs morsels | ✅ | Dynamic pricing |
| Operator-only public board creation | ✅ | |
| OTK-based board posting (Tier 0.5) | ✅ | 500-char limit |
| Catalogue (actions, agents, boards, hash, stats) | ✅ | All 7 endpoints |
| SHA-256 hash for change detection | ✅ | |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| B-1 | Board subscription / notifications | §12.3 | **Low** | RFC mentions board subscriptions (agents can subscribe to boards for notifications). No subscription mechanism exists — boards are poll-only. |

---

## 8. Observability & Admin

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Admin dashboard | ✅ | Agent/work/economy stats |
| Config view + update | ✅ | Runtime via PUT |
| Backup / restore | ✅ | Full JSON export/import |
| Role grants | ✅ | Operator grants to other owners |
| Extension hooks (11 hook points) | ✅ | CRUD via admin API |
| Health endpoint | ✅ | Uptime + heap usage |
| Agent listing (admin) | ✅ | |
| Admin stats | ✅ | |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| O-1 | Dashboard health thresholds | §14.3 | **Medium** | RFC specifies health alert thresholds (Table 14.3): burn/mint ratio, agent churn, work expiry rate, dispute rate, federation latency — with healthy/watch/danger zones. Dashboard returns stats but doesn't evaluate against thresholds or produce `warnings[]`. |
| O-2 | Economy metrics depth | §14.2 | **Medium** | RFC specifies: `total_morsels_in_circulation`, `total_minted_all_time`, `total_burned_all_time`, `transactions_today`, `morsels_transacted_today`, `network_fees_today`, `burned_today`, `daily_allowances_issued_today`. Not all of these are computed. |
| O-3 | Atomic config update format | §14.2, Appendix B | **Low** | RFC specifies `{"changes": [{"path": "morsel_policy.daily_allowance", "value": 75}]}` format with dot-path addressing. Implementation uses flat key-value update. |
| O-4 | Config schema with types/ranges | §14.2 | **Low** | RFC specifies `GET /v1/admin/config` returns full schema with types, ranges, and descriptions for each field. Implementation returns current values only. |

---

## 9. MCP Integration

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Streamable HTTP transport | ✅ | POST/GET/DELETE at `/v1/mcp` |
| 18 MCP tools (14 user + 4 admin) | ✅ | catalogue, agent, memory, action, work, wallet, board, storage + admin stats/agents/config/mint |
| OAuth 2.1 Dynamic Client Registration | ✅ | `/v1/mcp/register` |
| OAuth authorization + token exchange | ✅ | `/v1/mcp/authorize`, `/v1/mcp/token` |
| Token revocation | ✅ | `/v1/mcp/token/revoke` |
| OAuth server metadata | ✅ | `/.well-known/oauth-authorization-server` |
| Session management | ✅ | Per-session MCP server instances |

### Gaps ⚠️

| # | Gap | RFC Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| MCP-1 | MCP resource subscriptions | §5.7.5 | **Low** | MCP spec supports resource subscriptions (server pushes updates). Current SSE endpoint exists but resource change notifications aren't wired. |

---

## 10. Configuration Schema

### Implemented vs RFC Appendix B

The RFC (Appendix B) specifies **70+ configurable fields** across 13 categories. The implementation (`MeatConfig`) has **13 fields**.

| Config Category | RFC Fields | Implemented | Gap |
|----------------|:---:|:---:|:---:|
| Core (port, nodeId, dbUrl) | 3 | 3 | ✅ |
| Auth (jwtTtl, refreshAllowed, otkTtl, mcpEnabled) | 5 | 2 | ⚠️ Missing 3 |
| Morsel Policy (welcome, daily, cap, burn, fee, mint) | 6 | 5 | ⚠️ Missing mint cap |
| Trust Policy (initial, minPaid, autoFlagBelow) | 3 | 0 | ⚠️ Missing 3 |
| Quotas (memory, storage, actions, work queue) | 7 | 0 | ⚠️ Missing 7 |
| Extended Pricing (extra mem/storage, board post, routing) | 5 | 0 | ⚠️ Missing 5 |
| Federation (peering policy, hops, heartbeat, grace period) | 4 | 0 | ⚠️ Missing 4 |
| Rate Limits (global, per-tier, multipliers) | 5 | 5 | ✅ |
| Extension Hooks (11 hook points) | 11 | 11 | ✅ |
| Extended Features Toggle | 1 | 1 | ✅ |
| Keyed Browse | 1 | 1 | ✅ |
| Admin Password | 1 | 1 | ✅ |
| **Totals** | **~52** | **~29** | **~23 missing** |

### Key Missing Config Fields

| Field | RFC Default | Description |
|-------|-----------|-------------|
| `initial_trust_score` | 50 | Starting trust for new agents |
| `min_trust_for_paid_actions` | 10 | Minimum trust to publish paid actions |
| `auto_flag_below` | 20 | Auto-flag agents below this trust |
| `default_memory_quota_mb` | 10 | Total memory per agent |
| `default_storage_quota_mb` | 100 | Total storage per agent |
| `max_file_size_bytes` | 50MB | Max single file upload |
| `max_chunked_file_size_bytes` | 5GB | Max chunked upload total |
| `default_actions_max` | 20 | Max actions per agent |
| `work_queue_max_pending` | 10 | Max pending work per provider |
| `peering_policy` | closed | Open/closed peering |
| `max_relay_hops` | 3 | Max forwarding hops |
| `heartbeat_interval_seconds` | 300 | Peer ping frequency |
| `depeering_grace_period_hours` | 72 | Grace period before de-peer |
| `board_post_cost_morsels` | 5 | Cost per public board post |
| `cross_node_routing_per_request` | 1 | Morsel cost per routed request |
| `extra_memory_morsels_per_mb_month` | 10 | Overage charge for memory |
| `extra_storage_morsels_per_gb_month` | 100 | Overage charge for storage |
| `max_operator_mint_per_day` | 10,000 | Operator minting cap |
| `jwt_refresh_allowed` | true | Allow JWT refresh |
| `otk_ttl_seconds` | 60 | OTK lifetime |
| `mcp_enabled` | true | Enable/disable MCP |
| `portability_enabled` | true | Allow GAII porting |
| `porting_fee` | 50 | Morsels for porting |

---

## 11. Infrastructure & DevOps

### Implemented ✅

| Feature | Status | Notes |
|---------|--------|-------|
| Multi-stage Dockerfile | ✅ | node:22-alpine, non-root user |
| docker-compose with MongoDB | ✅ | Replica set for Prisma |
| ESLint config | ✅ | TypeScript rules |
| Vitest config | ✅ | Unit tests in test/unit/ |
| pnpm exclusively | ✅ | |
| Prisma schema (17 models) | ✅ | MongoDB provider |
| package.json `bin` field | ✅ | `"aimeat": "dist/index.js"` |
| `.env.example` | ✅ | |
| OpenAPI type generation script | ✅ | `generate:types` |
| Generated api-types.ts | ✅ | From openapi.yaml |

### Gaps ⚠️

| # | Gap | Spec Section | Severity | Description |
|---|-----|-------------|----------|-------------|
| I-1 | CLI with arg parsing | Implementation Prompt §4 | **Medium** | Implementation prompt specifies CLI entry with `yargs` or `commander`: `aimeat --port 8080`, `aimeat --db mongodb://...`, `aimeat init`, `aimeat backup`, `aimeat restore`. Current `index.ts` just starts the server — no arg parsing, no `init` wizard, no CLI backup/restore commands. |
| I-2 | Config file support | Implementation Prompt §4 | **Low** | Prompt specifies `aimeat.config.json` file support. Only env vars are supported. |
| I-3 | Node key persistence | Implementation Prompt §9 | **Low** | Prompt specifies saving node key to `~/.aimeat/node-key.json`. Current implementation stores node key only in the storage layer (lost on restart with in-memory storage — regenerated each time). |
| I-4 | Dockerfile base image version | — | **Low** | Dockerfile uses `node:22-alpine` but CLAUDE.md specifies Node.js 24.x runtime. Minor version mismatch. |
| I-5 | `bin/` directory | Implementation Prompt §2 | **Low** | Prompt specifies a `bin/aimeat.ts` CLI binary with shebang. Not created — `index.ts` used directly. |

---

## 12. Testing

### Current Coverage

| Test Type | Count | Files |
|-----------|:---:|:---:|
| Unit tests | 49 | 6 files (envelope, gaii, morsel, otk, tracking-code, trust) |
| E2E tests | 43+ | 1 file, 7 phases + GDPR |
| **Total** | **~92** | **7 files** |

### Gaps ⚠️

| # | Gap | Severity | Description |
|---|-----|----------|-------------|
| T-1 | Federation E2E tests | **Medium** | No E2E tests exercise actual cross-node communication. Federation tests only check peering request lifecycle (local state), not actual inter-node routing. |
| T-2 | MCP tool E2E tests | **Medium** | No tests for MCP Streamable HTTP transport or OAuth flow. MCP integration is untested. |
| T-3 | Dispute escalation flow E2E | **Low** | Auto-escalation (7d) and auto-resolve (30d) untested in E2E (timing constraint). Only dispute open/counter are tested. |
| T-4 | Micro-memory E2E tests | **Low** | No E2E coverage for micro-memory operations (add/del/mod/list/config). |
| T-5 | Storage visibility E2E tests | **Low** | Storage upload/download tested but visibility modes (public, owner-scoped) not exercised. |
| T-6 | Board post TTL E2E | **Low** | Board post TTL cleanup untested (timing dependent). |
| T-7 | Hook execution E2E | **Low** | Extension hooks (`pre_work_request`, `post_settlement`, etc.) not tested end-to-end. |
| T-8 | MongoDB storage adapter tests | **Low** | No integration tests for `MongoStorage`. Only `InMemoryStorage` exercised. |
| T-9 | Concurrent access tests | **Low** | No stress or concurrency tests for escrow, optimistic locking, or rate limiting under load. |

---

## 13. Documentation & Spec Alignment

### Implemented ✅

| Item | Status | Notes |
|------|--------|-------|
| OpenAPI 3.1 spec (openapi.yaml) | ✅ | 75+ paths, 88+ operations |
| MCP OAuth paths in spec | ✅ | 5 paths + well-known |
| Chunked upload paths in spec | ✅ | 4 paths |
| Admin extension paths in spec | ✅ | hooks, agents, stats, backup |
| Health endpoint in spec | ✅ | `/v1/health` |
| Auth OTK endpoint in spec | ✅ | `POST /v1/auth/otk` |
| Generated TypeScript types | ✅ | `src/generated/api-types.ts` |

### Gaps ⚠️

| # | Gap | Severity | Description |
|---|-----|----------|-------------|
| D-1 | GAII portability endpoints not in spec | **Low** | `POST /v1/agents/:gaii/port`, `POST /v1/agents/:gaii/export`, `POST /v1/agents/import`, `POST /v1/agents/:gaii/rekey` exist in code but not in openapi.yaml. |
| D-2 | Federation internal endpoints not in spec | **Low** | `POST /v1/federation/ping`, `/replicate`, `/catalogue-sync`, `/key-exchange`, `/trust-advisory` exist in code but not in openapi.yaml. |
| D-3 | Wallet history alias not in spec | **Low** | `GET /v1/wallet/history` is a legacy alias for `/transactions` — not documented in openapi.yaml. (Now also in OpenAPI.) |
| D-4 | OTK execute endpoint not in spec | **Low** | `GET /v1/otk/:key` (OTK execution) exists in code but not in openapi.yaml. |
| D-5 | Owner recovery endpoint not in spec | **Low** | `POST /v1/owners/:name/recover` exists in code but not in openapi.yaml. |

---

## 14. Priority Matrix

### High Priority (Core Protocol Compliance)

| # | Gap | Category | Impact | Effort |
|---|-----|----------|--------|--------|
| O-1 | Dashboard health thresholds | Observability | RFC §14.3 compliance; operators can't assess node health | Medium |
| O-2 | Economy metrics depth | Observability | Dashboard missing key economy indicators | Medium |
| F-1 | Relay node type | Federation | Cannot run stateless relay infrastructure | High |
| I-1 | CLI with arg parsing | Infrastructure | npm global install (`aimeat` CLI) doesn't work as spec'd | Medium |
| T-1 | Federation E2E tests | Testing | Cross-node routing untested | Medium |
| T-2 | MCP tool E2E tests | Testing | MCP integration untested | Medium |

### Medium Priority (Completeness)

| # | Gap | Category | Impact | Effort |
|---|-----|----------|--------|--------|
| F-3 | Multi-hop relay routing | Federation | Single-hop only; no hop counting | Medium |
| Config | 23 missing config fields | Configuration | Operators can't tune quotas, trust, pricing | Medium |
| E-3 | Priority queue pricing | Economy | `priority: 'high'` accepted but not charged 2x | Low |
| W-2 | Work queue max pending | Work Queue | No per-provider pending limit | Low |
| M-1 | Memory total quota (10MB) | Memory | Only per-key limits, not aggregate | Low |
| M-2 | Storage total quota (100MB) | Storage | Only per-file limits, not aggregate | Low |

### Low Priority (Polish / v1.3)

| # | Gap | Category | Impact | Effort |
|---|-----|----------|--------|--------|
| A-1 | OTK 60s post-use window | Auth | Browser compatibility edge case | Low |
| A-2 | `next_otk` pre-rotation | Auth | Convenience for session AI agents | Low |
| F-2 | Mirror node type | Federation | Redundancy/geographic distribution | High |
| F-6 | De-peering grace period | Federation | Immediate de-peer vs. 72h grace | Low |
| E-1 | Operator minting | Economy | No controlled inflation mechanism | Low |
| E-2 | Cross-node routing fee | Economy | 1 morsel/request not charged | Low |
| M-3 | Overage morsel charging | Memory/Storage | Quota exceeded → charge, not block | Medium |
| I-2 | Config file support | Infrastructure | `aimeat.config.json` | Low |
| I-3 | Node key persistence to disk | Infrastructure | Key regenerated on restart (in-memory) | Low |
| D-1–D-5 | Spec alignment | Documentation | Extra endpoints not in openapi.yaml | Low |
| B-1 | Board subscriptions | Boards | Poll-only, no push notifications | Medium |
| MCP-1 | MCP resource subscriptions | MCP | No server-push for resource changes | Low |

---

## Summary Metrics

| Metric | Value |
|--------|-------|
| **Total gaps identified** | 42 |
| **High priority** | 6 |
| **Medium priority** | 6 |
| **Low priority** | 30 |
| **RFC endpoint coverage** | 100% (all OpenAPI paths implemented) |
| **RFC feature coverage** | ~90% (gaps are mostly deeper behavior) |
| **Test coverage (domains)** | 12/17 domains covered |
| **Config completeness** | 29/52 fields (~56%) |

The implementation is production-ready for single-node deployments. Federation relay/mirror support and deeper observability are the primary areas needing work for multi-node production environments.

---

*Gap analysis generated 2026-02-26 — comparing implementation against RFC v1.2, OpenAPI 3.1 spec, and implementation prompt.*
