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:

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

Normal CI:

apophis verify --profile ci --changed

Nightly protocol or lifecycle testing:

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

Reproduction:

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:

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

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

Then in CI:

apophis verify --profile ci --changed

17.2 Platform team

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

17.3 Protocol-heavy service

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

17.4 LLM-generated service template

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:

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.