AkurAI-Framework / AKURAI_OPS_CONTRACT.md

Latest change ee7487eee78cd52cdafdcb22b6ff4bf57093d6e9 - feat: add --name flag to serve, standardize /api/health across all framework apps by Ólafur Búi Ólafsson

# AkurAI Ops Contract
#
# Every AkurAI application MUST expose these endpoints and follow this
# convention. RustAgent and the self-healing pipeline depend on uniformity.

## Required: Health Check

```
GET /api/health
→ 200 OK
Content-Type: application/json

{
  "app": "akurai-notes",           // string — systemd unit name, lowercase
  "version": "0.0.6",              // string — semver from VERSION file
  "status": "ok",                  // string — "ok" | "degraded" | "down"
  "uptime_seconds": 123456,        // number — process uptime
  "memory_bytes": 3145728          // number — RSS or PSS in bytes
}
```

**If Framework-based**, also include:
```
  "framework": "AkurAI-Framework",    // string — framework name
  "framework_version": "0.8.2"       // string — framework semver
```

## Required: Deploy Script

Every repo MUST have `./deploy.sh` that accepts:
```
./deploy.sh ec2        # publish only (no version bump)
./deploy.sh patch      # full release: gate → bump → tag → push → publish
./deploy.sh minor      # minor bump
./deploy.sh major      # major bump
```

Deploy MUST run these gates in order:
1. `cargo fmt --all -- --check` (or equivalent)
2. `cargo clippy --all-targets -- -D warnings` (or linter)
3. `cargo test --all` (or test runner)
4. Publish to EC2
5. `scripts/validate.sh` — MANDATORY post-deploy gate

## Required: Validate Script

Every repo MUST have `scripts/validate.sh` that:
- Exit 0 = healthy, safe to serve traffic
- Exit non-zero = broken, trigger rollback

Minimum checks:
1. Systemd unit active (`systemctl is-active <name>.service`)
2. Loopback health (`curl http://127.0.0.1:<port>/api/health`)
3. Public HTTPS health (`curl https://<domain>/api/health`)
4. If OIDC auth: `/auth/login` → 302 to auth.olibuijr.com
5. TLS cert expiry > 30 days
6. Health JSON matches contract schema

## Required: Agent Operations

For apps consumed by RustAgent (Notes MCP, PassVault MCP, CRM MCP):
- MCP endpoint at `https://<domain>/mcp`
- Bearer token auth via env var

## AKURAI_APPS.toml

The SSOT manifest in the Framework repo lists every app and its ops contract
conformance status. The `health_format` field tracks compliance:
- `"ok"` — conforms to contract
- `"needs_fix"` — deployed but non-conforming
- `"missing"` — no health endpoint at all