# APOPHIS

Behavioral confidence for Fastify services.

APOPHIS checks whether route behavior holds across operations, states, and protocol flows.

Inspired by [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021): instead of only checking payload shape, APOPHIS encodes intended behavior as executable contracts and verifies them with property-based and stateful testing.

Supported Node.js versions: 20.x and 22.x.

```bash
npm install apophis-fastify fastify @fastify/swagger
apophis init --preset safe-ci
apophis verify --profile quick --routes "POST /users"
```

`x-ensures` is an OpenAPI schema extension for behavioral contracts — statements about what a route must guarantee.

## Cross-Route Failure Example

Add one behavioral contract next to a route schema. APOPHIS can verify cross-route behavior, such as whether a resource created by one route is retrievable through another.

**Route:**

```javascript
import crypto from 'crypto';

app.post('/users', {
  schema: {
    'x-category': 'constructor',
    'x-ensures': [
      // BEHAVIORAL: Creating a user must make it retrievable
      'response_code(GET /users/{response_body(this).id}) == 200'
    ]
  }
}, async (request, reply) => {
  const { name } = request.body;
  const id = `usr-${crypto.createHash('sha256').update(name).digest('hex').slice(0, 8)}`;
  reply.status(201);
  return { id, name };
});
```

**APOPHIS output:**

```text
Contract violation
POST /users
Profile: quick
Seed: 42

Expected
  response_code(GET /users/{response_body(this).id}) == 200

Observed
  GET /users/usr-7d865e returned 404

Why this matters
  The resource created by POST /users is not retrievable.

Replay
  apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json

Next
  Check the create/read consistency for POST /users and GET /users/{id}.
```

JSON Schema cannot express this relationship. APOPHIS turns it into an executable check.

## Three Modes

| Mode | Purpose | Default Environments |
|---|---|---|
| `verify` | Deterministic CI and local contract verification | local, test, CI |
| `observe` | Runtime visibility and drift detection without blocking | staging, prod |
| `qualify` | Exercise scenarios, stateful flows, and configured chaos checks before release | local, test, staging |

## Quickstart: 3 Commands

```bash
# 1. Install
npm install apophis-fastify fastify @fastify/swagger

# 2. Scaffold
apophis init --preset safe-ci

# 3. Verify
apophis verify --profile quick --routes "POST /users"

# 4. Doctor
apophis doctor
```

See [docs/getting-started.md](docs/getting-started.md) for the full walkthrough.

## Trust and Safety

- **Deterministic replay**: Every failure includes a seed and a one-command replay.
- **Explicit test budget**: Control how many tests run with `runs: 10` in your preset.
- **CI-safe default path**: `verify` is deterministic and safe for CI pipelines.
- **Machine-readable output**: `--format json-summary` and `--format ndjson-summary` for CI dashboards.
- **Production-safe observe path**: `observe` is non-blocking by default. Blocking behavior requires explicit break-glass policy.
- **Qualify path gated away from prod**: `qualify` is blocked in production by default.
- **Monorepo workspace support**: `--workspace` fans out `verify` and `doctor` across all packages.
- **Explicit environment boundaries**: Config rejects unknown keys and unsafe environment mixes.

## LLM-Safe

APOPHIS gives coding agents a constrained, repeatable way to encode and verify behavior:

- Official scaffolds (`safe-ci`, `llm-safe`, `platform-observe`, `protocol-lab`)
- `apophis doctor` checks for missing dependencies, malformed config, and unsafe modes
- CI policy guards catch unknown keys, unsafe environments, and missing seeds
- Generated code follows the same pattern in every repo

See [docs/llm-safe-adoption.md](docs/llm-safe-adoption.md) for templates and CI policy.

## Full Documentation

- [Getting Started](docs/getting-started.md) — First route, first verify run, first replay
- [CLI Reference](docs/cli.md) — All 7 commands, global flags, exit codes
- [Verify Mode](docs/verify.md) — Deterministic contract verification
- [Observe Mode](docs/observe.md) — Runtime visibility and drift detection
- [Qualify Mode](docs/qualify.md) — Scenarios, stateful testing, chaos
- [Performance](docs/performance.md) — Repeatable benchmarks and CPU profiling
- [LLM-Safe Adoption](docs/llm-safe-adoption.md) — Scaffolds and CI guards
- [Protocol Extensions](docs/attic/protocol-extensions-spec.md) — JWT, X.509, SPIFFE, WIMSE

## License

MIT