apophis-fastify/docs/attic/PUBLIC_INTERFACE_REDESIGN.md

# APOPHIS Public Interface Redesign

Status: Proposal
Audience: APOPHIS maintainers, platform teams, Fastify service owners, LLM tooling authors
Scope: Outward-facing product contract, CLI, JS/TS integration surface, environment policy, and documentation architecture

Current strategy posture:

- Node-first
- Fastify-first
- no active multi-language roadmap
- Express remains only a possible future adapter, not a current strategy pillar

## 1. Purpose

This document proposes a new outward-facing contract for APOPHIS that makes the tool easier to adopt, safer to operate, and easier to use correctly from both human-written and LLM-generated Fastify services.

The core idea is simple:

- shrink the day-1 public API
- make safety boundaries structural, not advisory
- move from method sprawl to explicit product modes
- make CLI the primary orchestration surface
- keep behavioral expressiveness and protocol realism available, but progressively disclosed

This document does not propose removing APOSTL, behavioral contracts, scenario execution, stateful testing, or chaos. It proposes repackaging them so the default path is smaller, clearer, and harder to misuse.

It also proposes a terminology shift:

- `verify` for deterministic behavioral confidence
- `observe` for runtime visibility without blocking by default
- `qualify` for proving a service holds up under realistic and adverse conditions

## 2. Why Change

The current system has real strengths:

- strong behavioral testing beyond schema validation
- cross-operation contracts
- protocol flow support through variants and scenarios
- runtime guardrails
- outbound contract and chaos foundations

The current outward shape also creates adoption friction:

- too many top-level concepts arrive at once
- test-only and runtime features live too close together
- production safety is partly enforced in policy, not fully encoded in interface shape
- advanced features are discoverable before the safe path is fully learned
- generated code can misuse broad APIs and ambiguous options
- documentation must explain too many surfaces at the same time

The result is that APOPHIS has broad capability, but is harder than necessary to trust quickly.

## 3. Design Goals

### 3.1 Primary goals

- Make first success possible in under 15 minutes.
- Make CI-safe behavior the default product posture.
- Preserve behavioral expressiveness and realistic protocol-flow coverage.
- Make production-risking features impossible to activate by accident.
- Make failure output deterministic and replayable.
- Make the public surface easy for LLMs to use correctly.

### 3.2 Secondary goals

- Reduce docs drift by narrowing the canonical path.
- Improve packaging clarity for teams that only want the core path.
- Enable platform teams to adopt policy packs without forcing them on smaller teams.

### 3.3 Non-goals

- Replacing APOSTL immediately with a different contract language.
- Removing advanced testing capabilities.
- Requiring every team to use runtime enforcement.
- Converting APOPHIS into a general observability platform.
- Pursuing native multi-language or multi-runtime expansion at this time.
- Treating Express, Python, Go, or Java support as required for the current redesign.

## 3.4 Product Boundary For This Proposal

This redesign is intentionally scoped to the current product reality:

- APOPHIS is a Node product today.
- APOPHIS is a Fastify product first.
- The CLI and outward API redesign are being proposed to improve the Fastify experience first.
- Any future Express support is optional and should be treated as a later adapter opportunity, not as a driver of current architecture decisions.
- Python, Go, Java, and other runtime ambitions are explicitly out of scope for this proposal.

## 4. Design Principles

1. Safe by default.
2. Deterministic by default.
3. One obvious path for common jobs.
4. Progressive disclosure for advanced capability.
5. Product modes beat large unstructured option sets.
6. Runtime and lab features must be clearly separated.
7. Unknown config must fail fast.
8. Docs should teach tasks, not feature inventory.
9. LLM-facing APIs must be narrower than human power-user internals.
10. Realistic protocol-flow coverage is a tier, not a prerequisite.

## 5. Core Jobs To Be Done

### 5.1 Production Fastify hardening

When a Fastify team hardens a production service, it needs to:

- catch behavioral regressions before merge
- detect runtime contract drift without risking outages
- replay failures deterministically
- selectively deepen realism for critical flows
- operate within clear environment-specific safety rules

### 5.2 LLM-coded Fastify services

When a team uses coding agents to build or maintain Fastify services, it needs to:

- give the agent a constrained setup sequence with tested commands and templates
- prevent hallucinated config and unsafe hook usage
- make CI reject weak or malformed contract setups
- provide official templates the agent can fill safely
- keep the safe path much simpler than the expert path

## 6. User Journeys

### 6.1 Journey A: A product team wants CI confidence quickly

Job:
Catch behavioral regressions before merge with minimal setup.

Journey:

1. The team installs `apophis-fastify` and `@fastify/swagger`.
2. The team runs `apophis init --preset safe-ci`.
3. The CLI scaffolds a small config file, example route guidance, and a package script.
4. The team adds one `x-ensures` contract to one critical route.
5. The team runs `apophis verify --routes "POST /users"`.
6. The CLI returns pass/fail, a seed, and a replay command if it fails.
7. The team expands coverage route by route.

Success criteria:

- no runtime hooks required
- no scenario/chaos learning required
- failure output is actionable on day one

### 6.2 Journey B: A platform team wants safe runtime visibility

Job:
See contract drift in staging and production without making APOPHIS a new outage source.

Journey:

1. The team enables `observe` mode in staging.
2. Violations emit logs, metrics, and traces but do not fail requests.
3. The team tunes sampling and route allowlists.
4. The team promotes the same observe profile to production.
5. The team tracks top contract violations as hardening backlog.

Success criteria:

- no customer-visible failures from APOPHIS by default
- clear route-level diagnostics
- explicit escalation path if the org chooses stronger enforcement later

### 6.3 Journey C: A critical auth or billing team wants deeper realism

Job:
Exercise multi-step, negotiated, or failure-path behavior without contaminating normal CI.

Journey:

1. The team creates a `qualify` profile for an OAuth, payments, or retry flow.
2. The team runs `apophis qualify --profile oauth-nightly --seed 42` in nightly CI or staging.
3. Failures produce minimized traces, seeds, and replay commands.
4. High-value failures are promoted into deterministic replay coverage.

Success criteria:

- qualify mode has broad scope
- qualify mode is not the day-1 default
- non-prod boundaries are enforced by the tool, not just documented

### 6.4 Journey D: A team uses LLMs to generate Fastify services

Job:
Make it easy for agents to set up safe, correct contract testing and hard to invent unsupported integration patterns.

Journey:

1. The team uses `apophis init --preset llm-safe`.
2. The CLI emits canonical scaffolds, config schema, CI checks, and a route template.
3. The agent fills in route schemas and behavioral formulas inside approved structure.
4. CI runs `apophis doctor` and `apophis verify`.
5. Unknown keys, unsafe modes, or malformed setup fail immediately.

Success criteria:

- the agent uses a constrained vocabulary
- generated code follows the same pattern in every repo
- the policy engine catches drift before merge

## 7. Proposed Product Model

The public product model is organized around three modes.

| Mode | Primary use | Default environments | Blocking behavior | Intended user |
|---|---|---|---|---|
| `verify` | Deterministic CI and local contract verification | local, test, CI | yes, in test flow | app teams |
| `observe` | Runtime visibility and drift detection | staging, prod | no, by default | platform teams |
| `qualify` | Deep realism, scenarios, stateful, chaos, adversity checks | local, test, staging | yes, in lab flow | specialist teams |

This replaces the need for users to understand the full internal method graph before they can get value.

## 8. Proposed Public Contract

### 8.1 Primary contract with users

The tool promises:

- stable high-level modes
- deterministic reproduction of failures in `verify` and `qualify`
- non-blocking runtime behavior by default in `observe`
- explicit environment safety gating
- CLI-first workflows that work without custom harness code

### 8.2 What remains stable in route schemas

Route authoring remains centered on:

- `x-requires`
- `x-ensures`
- `x-category`
- `x-timeout`
- JSON Schema request and response definitions

APOSTL remains the behavioral contract language for the foreseeable future.

### 8.3 What changes outwardly

Users stop thinking first in terms of:

- `contract()`
- `stateful()`
- `scenario()`
- `test.*`
- `chaos` knobs

Users start thinking first in terms of:

- `verify`
- `observe`
- `qualify`
- profiles and presets
- replayable failures

## 9. CLI-First Interface

### 9.1 Why CLI-first

A CLI is the right top-level orchestration surface because it:

- standardizes CI entrypoints
- removes harness boilerplate from every repo
- gives LLMs a small command vocabulary
- centralizes policy validation
- makes docs task-oriented instead of API-first

### 9.2 Proposed commands

| Command | Purpose |
|---|---|
| `apophis init` | Scaffold config, scripts, and example usage |
| `apophis verify` | Run deterministic contract verification |
| `apophis observe` | Validate runtime observe configuration and reporting setup |
| `apophis qualify` | Run scenario, stateful, protocol, or chaos-driven qualification |
| `apophis replay` | Replay a failure using seed and stored trace |
| `apophis doctor` | Validate config, environment safety, docs/example correctness |
| `apophis migrate` | Check and rewrite deprecated config or API usage |

### 9.3 Example CLI flows

First-time setup:

```bash
apophis init --preset safe-ci
apophis verify --profile quick --routes "POST /users"
```

Normal CI:

```bash
apophis verify --profile ci --changed
```

Nightly protocol or lifecycle testing:

```bash
apophis qualify --profile oauth-nightly --seed 42
apophis qualify --profile lifecycle-deep --seed 42
```

Reproduction:

```bash
apophis replay --seed 42 --trace reports/apophis/failure-2026-04-28.json
```

## 10. JS/TS Integration Surface

The Fastify plugin remains important, but its outward role becomes smaller.

### 10.1 Proposed simplified Fastify surface

The long-term goal is a smaller, more mode-oriented decoration surface such as:

```ts
fastify.apophis.verify(opts?)
fastify.apophis.observe(opts?)
fastify.apophis.qualify(opts?)
fastify.apophis.spec()
fastify.apophis.cleanup()
```

### 10.2 Compatibility aliases

During migration, current methods remain as aliases:

- `contract()` maps to `verify({ kind: 'contract' })`
- `stateful()` maps to `qualify({ kind: 'stateful' })`
- `scenario()` maps to `qualify({ kind: 'scenario' })`

These aliases should remain for at least one major transition cycle.

### 10.3 Test-only helpers

The `test.*` namespace stays test-only and should become even more explicitly non-default.

Long-term direction:

- keep helper APIs under a clearly named `lab` or `test` namespace
- make them unavailable in prod builds and prod runtime startup
- document them only in advanced or pack-specific docs

## 11. Profiles, Presets, and Policy Packs

### 11.1 Profiles

Profiles replace low-level tuning as the first user decision.

Suggested built-in profiles:

| Profile | Use case |
|---|---|
| `quick` | local smoke verification |
| `ci` | normal PR checks |
| `deep` | fuller nightly verification |
| `oauth-nightly` | protocol qualification |
| `staging-observe` | runtime visibility in staging |

### 11.2 Presets

Presets configure initial install posture.

Suggested presets:

- `safe-ci`
- `platform-observe`
- `llm-safe`
- `protocol-lab`

### 11.3 Policy packs

Policy packs are organization-level overlays.

Suggested packs:

- `baseline`
- `regulated`
- `high-assurance`

These packs govern:

- which modes are allowed in which environments
- which routes are protected from qualify mode
- which reporting sinks are mandatory
- whether stronger runtime enforcement can ever be enabled

## 12. Environment Safety Matrix

| Capability | local | test/CI | staging | prod |
|---|---|---|---|---|
| `verify` | enabled | enabled | optional | optional, usually off |
| `observe` | optional | optional | enabled | enabled |
| `qualify: scenario` | enabled | enabled | enabled with allowlist | disabled by default |
| `qualify: stateful` | enabled | enabled | synthetic-only | disabled by default |
| `qualify: chaos` | enabled | enabled | canary-only | disabled by default |
| outbound mocks | enabled | enabled | allowlisted only | disabled by default |
| runtime throw-on-violation | optional | optional | exceptional | disabled by default |

Operational rule:

Production must never inherit qualify capabilities accidentally from a generic config file.

## 13. Verisimilitude Strategy

The redesign preserves realism by making it a tiered concept instead of a day-1 requirement.

Suggested realism tiers:

| Tier | Meaning | Typical features |
|---|---|---|
| Schema | Structural confidence | schema inference, status/body checks |
| Behavioral | Cross-operation confidence | APOSTL, pure GET references, invariants |
| Realistic | Protocol and failure realism | variants, scenario, stateful, chaos, outbound contracts |

This keeps the user journey legible:

- start with schema plus behavioral verification
- add realistic qualification only where risk justifies complexity

## 14. LLM-Safe Design Requirements

The public surface should be intentionally shaped for generated code.

Requirements:

- config schemas reject unknown keys
- presets are preferred over raw option objects
- official scaffolds are canonical and tested in CI
- CLI commands are stable and small in number
- environment-dangerous features require explicit noisy opt-in
- generated code should not need to touch internal registries by default

Recommended official scaffolds:

- `service` scaffold
- `route` scaffold
- `verify` test scaffold
- `observe` config scaffold
- `qualify` profile scaffold

Recommended CI policy checks:

- no test-only features enabled in prod profile
- deterministic seed policy required for `verify`
- unknown config key hard failure
- docs example smoke tests
- replay artifact generated for qualify failures

## 15. Documentation Architecture

The documentation set should be rebuilt around jobs and product modes.

### 15.1 Canonical docs stack

| Document | Purpose |
|---|---|
| `README.md` | 5-minute value proposition and install path |
| `docs/getting-started.md` | first route, first verify run, first replay |
| `docs/PUBLIC_INTERFACE_REDESIGN.md` | product contract and long-term outward design |
| `docs/GITHUB_SITE_STRATEGY.md` | homepage messaging, first-signal funnel, and GitHub Pages structure |
| `docs/cli.md` | command reference and environment semantics |
| `docs/runtime-observe.md` | runtime visibility, telemetry, policy |
| `docs/qualify.md` | scenarios, stateful, chaos, and qualification guidance |
| `docs/llm-safe-adoption.md` | scaffolds, CI guards, generated-service policy |
| `docs/protocol-extensions-spec.md` | protocol domain specifics |

### 15.2 Documentation rules

1. Canonical docs must describe only supported current behavior.
2. Design or historical material must live in attic unless it is actively steering implementation.
3. Every public example must be smoke-tested in CI.
4. Every advanced feature doc must state environment limits explicitly.
5. Expert APIs should be documented after the safe path, never before it.

### 15.3 Writing order for users

The docs should guide users in this order:

1. why APOPHIS exists
2. how to get a first verify pass or failure
3. how to replay and fix a failure
4. how to observe safely in runtime
5. how to use qualify mode selectively
6. how to adopt advanced packs and policy controls

## 16. Migration Strategy

### 16.1 Outward migration phases

Phase 1: additive

- ship CLI commands alongside current API
- add `verify`, `observe`, and `qualify` aliases
- begin updating docs to mode-first language

Phase 2: guided

- emit deprecation guidance for old names in docs and optional runtime warnings in test mode
- add `apophis migrate --check`

Phase 3: policy tightening

- disallow ambiguous or unsafe legacy config in new presets
- require explicit break-glass style opt-in for any prod-risking mode

Phase 4: major cleanup

- remove deprecated outward names after migration window
- keep attic history and codemods for older repos

### 16.2 Compatibility policy

- no semantic surprise during alias period
- deprecations must include exact replacement guidance
- current route schema contract annotations remain valid

## 17. Example End-to-End Experience

### 17.1 Small product team

```bash
apophis init --preset safe-ci
apophis verify --profile quick --routes "POST /users"
```

Then in CI:

```bash
apophis verify --profile ci --changed
```

### 17.2 Platform team

```bash
apophis init --preset platform-observe
apophis observe --profile staging-observe --check-config
```

### 17.3 Protocol-heavy service

```bash
apophis init --preset protocol-lab
apophis verify --profile ci
apophis qualify --profile oauth-nightly --seed 42
```

### 17.4 LLM-generated service template

```bash
apophis init --preset llm-safe
apophis doctor
apophis verify --profile quick
```

## 18. Recommended Immediate Changes

These changes give the highest value without requiring a full rewrite.

1. Introduce a CLI with `init`, `verify`, `qualify`, `replay`, and `doctor`.
2. Add outward aliases for `verify` and `qualify` while preserving current methods.
3. Introduce named profiles and presets before changing deeper internals.
4. Rework docs around mode-first language and JTBD.
5. Add CI smoke tests for all public docs examples.
6. Add config validation that rejects unknown keys and unsafe environment mixes.

## 19. Medium-Term Design Direction

1. Precompile or prepare contracts before runtime observe mode.
2. Split expert capabilities into packs or clearly bounded modules.
3. Narrow the extension story for common users to capability-level registration, not full lifecycle complexity.
4. Make replay artifacts a first-class product primitive.
5. Add policy-pack support for regulated and high-assurance environments.

## 20. Success Metrics

The redesign succeeds if it improves:

- time to first useful signal
- rate of successful first-run adoption
- docs example accuracy
- deterministic replay success rate
- production safety confidence
- LLM-generated setup correctness

Suggested metrics:

- median time from install to first passing or failing `verify` run
- percent of users adopting a preset rather than raw manual config
- percent of docs examples validated in CI
- percent of failures with successful replay on first attempt
- number of prod incidents caused by APOPHIS itself, target zero
- number of generated-service repos passing `doctor` on first CI run

## 21. Why `qualify`

`qualify` is a better outward verb than `experiment`.

`experiment` implies:

- optional exploration
- scientific curiosity
- possible nondeterminism
- low operational seriousness

`qualify` implies:

- proving a system is fit for intended conditions
- validating behavior under realistic and adverse conditions
- release and readiness posture
- stronger engineering language borrowed from safety, materials, and reliability practice

That is closer to the actual job.

Users are not merely experimenting with their service. They are asking:

- does it hold up?
- is it fit for service?
- do the guarantees still hold under protocol flow, state evolution, and adversity?

The intended mental model becomes:

- `verify`: is the behavior correct?
- `observe`: is the live system drifting?
- `qualify`: do scenario, stateful, and chaos checks pass for critical flows?

## 22. First Signal Funnel

The first useful signal is not “APOPHIS generated tests.”

The first useful signal is:

One route-level behavioral contract catches a retrievability bug that schema validation and ordinary happy-path tests miss.

### 22.1 Earliest signal target

Target time to first signal:

- 5 to 10 minutes after install

Target setup:

1. install dependencies
2. run `apophis init --preset safe-ci`
3. add one behavioral `x-ensures` clause to one important route
4. run `apophis verify --profile quick --routes "POST /users"`

Target result:

- APOPHIS checks an important cross-operation expectation under generated inputs, or reports a reproducible counterexample

### 22.2 Canonical first-signal example

Route under test:

- `POST /users`

Behavioral contract:

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

Why this matters:

- JSON Schema cannot express this relationship
- many teams would not write a bespoke test for it on day one
- this is a production-shaped failure mode

The first signal lands when APOPHIS says, in effect:

You returned `201`, but the created user is not actually retrievable.

That is the moment the product demonstrates its category value.

### 22.3 Funnel stages

| Stage | User question | APOPHIS answer |
|---|---|---|
| Install | Can I get this running quickly? | `apophis init` gives a constrained setup sequence |
| First route | What should I write? | one behavioral example on one critical route |
| First run | What does it do for me? | `verify` checks a meaningful relationship |
| Failure | Can I act on this now? | route, formula, seed, replay command, likely fix |
| Trust | Is this more than schema validation? | yes, it checked behavior across operations |
| Expansion | Where do I go next? | add more `verify`, then `observe`, then selective `qualify` |

### 22.4 Design rules for the first-signal funnel

1. Optimize for first meaningful signal, not first green checkmark.
2. Put one canonical bug-shaped example in every quickstart.
3. Failure output must read like a product diagnosis, not parser internals.
4. Replay must be obvious and copy-pasteable.
5. The next step after the first signal must be explicit.

## 23. GitHub Site and Homepage Strategy

The GitHub site or project homepage should show the first useful signal before it explains the full system.

### 23.1 The page must answer five questions fast

1. What is APOPHIS?
2. Why is this different from schema validation and hand-written integration tests?
3. What is the first meaningful signal I will get?
4. How quickly can I get that signal?
5. Why should I trust this in a production Fastify workflow?

### 23.2 Recommended page structure

1. Hero
2. Immediate behavior example
3. Why this matters in production
4. Three mode model
5. First-signal quickstart
6. Trust and safety section
7. LLM-safe section
8. Deeper use cases
9. CTA and navigation onward

### 23.3 Hero copy direction

Headline direction:

- Behavioral confidence for Fastify services.
- Catch real API regressions schema validation misses.

Supporting copy direction:

- APOPHIS lets you write behavioral contracts next to route schemas and check behavior across operations, states, and protocol flows.

Primary CTA:

- Find a behavioral bug in 10 minutes

Secondary CTA:

- See the behavioral bug it catches

### 23.4 Immediate behavior section

The homepage should show a side-by-side:

Left:

- one route with a tiny `x-ensures` behavioral clause

Right:

- the APOPHIS failure output showing the real bug

The point is not API completeness. The point is a concrete category example.

### 23.5 Meaning section

The homepage should explicitly say why this matters:

- schema validation checks shape
- APOPHIS checks behavior
- production outages often come from behavior drift as well as invalid payload shapes
- this matters even more in fast-moving and LLM-assisted codebases

### 23.6 Trust section

Trust content should include:

- deterministic replay
- CI-safe verify path
- non-blocking observe path
- qualify path for deeper realism
- explicit production safety boundaries

### 23.7 LLM-safe section

This section should explain:

- APOPHIS gives coding agents a constrained, repeatable way to encode and verify behavior
- official templates and `doctor` checks reduce hallucinated setup
- this is a practical guardrail for AI-generated Fastify services

### 23.8 What the homepage should not do

It should not:

- lead with the parser
- lead with extension architecture
- lead with every advanced feature
- bury the first useful signal behind long theory
- sound like a generic schema tooling site

The first screen should communicate category, value, and a concrete example.

### 23.9 Success criteria for the site

The site succeeds if a new visitor can say:

- I understand what APOPHIS is
- I see why it matters
- I know what the first meaningful win looks like
- I know which command to run first

## 24. Recommended Homepage Content Blocks

Suggested GitHub Pages layout:

1. Hero
2. Behavior-check code and failure output
3. Why behavior beats shape-only validation
4. `verify / observe / qualify` explainer
5. First-signal quickstart
6. Production hardening story
7. LLM-coded services story
8. Protocol and advanced qualification examples
9. Documentation links

## 25. Final Position

APOPHIS should expose a small default CLI surface with advanced qualification features behind explicit profiles.

Users should not need to learn the full internal engine to get value.

The new outward contract should therefore be:

- CLI-first
- mode-first
- preset-first
- deterministic by default
- production-safe by construction
- expressive only when explicitly asked to be

That is how APOPHIS can preserve advanced workflows while remaining usable for everyday Fastify teams and LLM-generated services.