John Dvorak
6c39bd0a6c
- Fix const inference bug: wrap inferred contracts with status-code guards - Add integration test for status-guarded contract inference - Tighten and deduplicate docs across verify, qualify, getting-started, cli - Fix broken cross-references and TypeScript→JavaScript conversions - Fix factual errors: license, Date.now(), sampling defaults, cache env - Add missing features: --workspace, --generation-profile, json-summary formats - Move stale extension docs (AUTH-RATE-LIMIT-REVISED, HTTP-EXTENSIONS) to attic - Update PLUGIN_CONTRACTS_SPEC status to Implemented - Build: clean | Tests: 849 pass, 0 fail
123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
# APOPHIS Homepage
|
|
|
|
## Hero
|
|
|
|
**Behavioral confidence for Fastify services.**
|
|
|
|
APOPHIS lets you write behavioral contracts next to route schemas and check behavior across operations, states, and protocol flows.
|
|
|
|
[Find a behavioral bug in 10 minutes](#quickstart)
|
|
[See the bug APOPHIS catches](#behavior-example)
|
|
|
|
## Behavior Example
|
|
|
|
One route contract. One create/read consistency bug.
|
|
|
|
**Route:**
|
|
|
|
```javascript
|
|
app.post('/users', {
|
|
schema: {
|
|
'x-category': 'constructor',
|
|
'x-ensures': [
|
|
'response_code(GET /users/{response_body(this).id}) == 200'
|
|
]
|
|
}
|
|
}, async (request, reply) => {
|
|
const { name } = request.body;
|
|
const id = `usr-${Date.now()}`;
|
|
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-123 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.
|
|
|
|
## Why It Matters
|
|
|
|
- **JSON Schema checks shape**: Does the response have the right fields?
|
|
- **APOPHIS checks behavior**: Does creating a user make it retrievable? Does updating change persist? Does deleting make it inaccessible?
|
|
|
|
Production outages often come from behavior drift as well as invalid payload shapes. APOPHIS checks behavior at the route-contract layer.
|
|
|
|
## 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** | Run scenario, stateful, and chaos checks for critical flows | local, test, staging |
|
|
|
|
## Quickstart
|
|
|
|
Three commands to the first targeted behavior check:
|
|
|
|
```bash
|
|
npm install apophis-fastify fastify @fastify/swagger
|
|
apophis init --preset safe-ci
|
|
apophis verify --profile quick --routes "POST /users"
|
|
```
|
|
|
|
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.
|
|
- **CI-safe default path**: `verify` is deterministic and safe for CI pipelines.
|
|
- **Production-safe observe path**: `observe` is non-blocking by default.
|
|
- **Qualify path gated away from prod**: `qualify` is blocked in production by default.
|
|
- **Explicit environment boundaries**: Config rejects unknown keys and unsafe environment mixes.
|
|
|
|
## LLM-Coded Services
|
|
|
|
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.
|
|
|
|
## Advanced Cases
|
|
|
|
- [Protocol flows](docs/qualify.md) — OAuth, multi-step negotiations
|
|
- [Stateful lifecycle testing](docs/qualify.md) — Constructor/mutator/observer/destructor sequences
|
|
- [Outbound dependency contracts](docs/protocol-extensions-spec.md) — WIMSE, SPIFFE, JWT
|
|
- [Chaos and adversity qualification](docs/qualify.md) — Controlled fault injection
|
|
|
|
## Operator Resources
|
|
|
|
- [Troubleshooting matrix](docs/troubleshooting.md) — Categorized failure classes with resolution steps
|
|
- [Adoption certification scorecard](adoption-certification-scorecard.md) — Review template for team rollout
|
|
|
|
## CTAs
|
|
|
|
- [Start with verify](docs/verify.md)
|
|
- [Read the 10-minute guide](docs/getting-started.md)
|
|
- [See qualification examples](docs/qualify.md)
|