John Dvorak
8d7382417d
- Cite arxiv 2602.23922 (Invariant-Driven Automated Testing) in all major docs - Add Progressive Complexity section to SKILL.md for LLM guidance - Fix SKILL.md Fast Start example to use deterministic ID generation - Fix getting-started.md failure output inconsistency - Fix auth-patterns.md TypeScript syntax in JS doc - Fix fastify-structure.md Date.now() in test helper - Fix observe.md misleading workspace heading - Build: clean | Tests: 849 pass, 0 fail
132 lines
4.5 KiB
Markdown
132 lines
4.5 KiB
Markdown
# 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.
|
|
- **Generation profile aliases**: Control test budget with `--generation-profile quick|standard|deep`.
|
|
- **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/protocol-extensions-spec.md) — JWT, X.509, SPIFFE, WIMSE
|
|
|
|
## License
|
|
|
|
MIT
|