## Why

Phase 4 made SentryAgent.ai discoverable and adoptable — developers can now find, register, and use agent identities through the portal, CLI, and marketplace. Phase 5 completes the platform's ambition: to become the definitive global standard for agent identity. This requires three things: (1) language coverage parity (Rust SDK — the final missing language), (2) protocol innovation (A2A delegation — agents authorizing agents), and (3) ecosystem lock-in through compliance certification, advanced analytics, and developer tooling that competitors cannot match.

## What Changes

- **Rust SDK** (`sdk-rust/`): The last major language SDK. Rust developers are disproportionately building high-performance and safety-critical AI agents. Supporting Rust signals platform maturity and seriousness.
- **Agent-to-Agent (A2A) Authorization**: A new authorization primitive — one agent delegates authority to another agent via a verifiable delegation chain. Critical for multi-agent orchestration workflows (e.g., an orchestrator agent issuing sub-tasks to worker agents). New endpoints: `POST /oauth2/token/delegate` and `POST /oauth2/token/verify-delegation`. New DB table: `delegation_chains`.
- **Advanced Analytics Dashboard**: Tenant-facing usage analytics — agent activity heatmaps, token issuance trends, credential rotation frequency, API call pattern breakdowns. New endpoints under `GET /analytics/`. Extends the existing React dashboard (`dashboard/`).
- **Public API Gateway & Rate Limiting SaaS**: Multi-tier rate limits (free/pro/enterprise) enforced at the gateway layer with self-service tier upgrade. New endpoints `GET /tiers` and `POST /billing/upgrade`. Extends the existing Stripe billing and free-tier enforcement from Phase 4.
- **Developer Experience (DX) Improvements**: Swagger UI v5 with `elements` theme in the developer portal, an SDK code generator endpoint (`GET /sdk/scaffold/:agentId`), and a `sentryagent scaffold` CLI command that generates a language-specific starter project with agent auth pre-wired.
- **AGNTCY Compliance Certification Package**: Auto-generated AGNTCY compliance report, agent card export per the AGNTCY spec, a Jest-based interoperability test suite, and a certification guide document. Positions SentryAgent.ai as the reference implementation for AGNTCY.

## Capabilities

### New Capabilities

- `rust-sdk`: Async Rust SDK with `tokio` + `reqwest`, full 14-endpoint coverage, typed error model, thread-safe TokenManager
- `a2a-authorization`: Delegation token issuance and chain verification — agents can authorize other agents with scoped, auditable delegation chains
- `analytics-dashboard`: Tenant analytics — heatmaps, trends, rotation frequency, API patterns — rendered in the existing web dashboard
- `api-gateway-tiers`: Multi-tier rate limits with self-service upgrade; tier definitions returned from `GET /tiers`; upgrade initiated via `POST /billing/upgrade`
- `developer-experience`: Swagger UI v5 with elements theme, SDK scaffold generator endpoint, `sentryagent scaffold` CLI command
- `agntcy-compliance`: Machine-readable compliance report, agent card export, AGNTCY interoperability test suite, certification documentation

### Modified Capabilities

- `web-dashboard` (`dashboard/`): New Analytics tab with charts (recharts) and metric drill-downs
- `cli-tool` (`cli/`): New `sentryagent scaffold` command added to existing CLI package
- `developer-portal` (`portal/`): Swagger UI upgraded from v4 to v5 with elements theme
- `billing-metering`: Extended with `POST /billing/upgrade` self-service tier upgrade; multi-tier rate limit enforcement
- `monitoring`: New Prometheus metrics for delegation chain depth, analytics query latency, scaffold generation count

## Impact

**Code affected:**
- `sdk-rust/` — new Rust crate (entirely new directory)
- `src/services/DelegationService.ts` — new service for A2A delegation
- `src/controllers/DelegationController.ts` — new controller for delegation endpoints
- `src/services/AnalyticsService.ts` — new service for tenant analytics queries
- `src/controllers/AnalyticsController.ts` — new controller for analytics endpoints
- `src/routes/analytics.ts` — new Express router
- `src/routes/delegation.ts` — new Express router
- `src/routes/tiers.ts` — new Express router for tier definitions
- `src/services/BillingService.ts` — extended with `upgradeTier()` method
- `src/controllers/BillingController.ts` — extended with `POST /billing/upgrade` handler
- `src/services/ScaffoldService.ts` — new service generating scaffold ZIP archives
- `src/controllers/ScaffoldController.ts` — new controller for scaffold endpoint
- `src/middleware/tierRateLimiter.ts` — new middleware enforcing per-tier limits
- `src/infrastructure/migrations/008_add_delegation_chains.sql` — new migration
- `src/infrastructure/migrations/009_add_analytics_aggregates.sql` — new migration
- `dashboard/src/pages/Analytics.tsx` — new analytics page added to existing dashboard
- `dashboard/src/components/charts/` — new chart components (heatmap, trends, rotation)
- `portal/app/api-explorer/page.tsx` — upgrade Swagger UI to v5 with elements theme
- `cli/src/commands/scaffold.ts` — new scaffold command in existing CLI
- `docs/agntcy/certification-guide.md` — new AGNTCY certification documentation
- `tests/agntcy/interoperability.test.ts` — new AGNTCY interoperability test suite

**New dependencies (requires CEO approval):**

| Dependency | Workspace | Justification |
|---|---|---|
| `tokio` (Rust) | `sdk-rust/` | Async runtime — standard for async Rust; no viable alternative |
| `reqwest` (Rust) | `sdk-rust/` | HTTP client for Rust — most popular, async-native, TLS-enabled |
| `serde` + `serde_json` (Rust) | `sdk-rust/` | JSON serialization in Rust — de facto standard, zero alternatives |
| `uuid` (Rust crate) | `sdk-rust/` | UUID v4 generation in Rust — standard, lightweight |
| `thiserror` (Rust crate) | `sdk-rust/` | Ergonomic typed error derive macros — DRY error definitions |
| `recharts` | `dashboard/` | React charting library — composable, TypeScript-native, well-maintained |
| `date-fns` | `dashboard/` | Date manipulation for analytics trend queries — lightweight, tree-shakeable |
| `archiver` | `src/` (API) | ZIP archive creation for scaffold generator — battle-tested Node.js archiver |
| `@stoplight/elements` | `portal/` | Swagger UI v5 / Elements theme — modern, interactive, component-based API docs |

**Approved scope (CEO-confirmed 2026-04-02):** WS1 → WS2 → WS5

**Deferred to Phase 6:** WS3 (Advanced Analytics), WS4 (API Gateway Tiers), WS6 (AGNTCY Compliance Certification)
