diff --git a/APOPHIS_ADOPTION_AUDIT.md b/APOPHIS_ADOPTION_AUDIT.md index a924c6d..43f7412 100644 --- a/APOPHIS_ADOPTION_AUDIT.md +++ b/APOPHIS_ADOPTION_AUDIT.md @@ -126,8 +126,6 @@ The implementation supports runtime observation only when the application explic - Integration tests prove sink sync failures and async rejections never change route responses. - Integration tests prove sampling: 0 suppresses all events; sampling: 1 emits expected `contract.pass`/`contract.violation` events. -**Still open:** A future `apophis observe --app ./app.ts` mode that imports and starts a service for local/staging smoke observation. Production observation itself is now programmatic and active through plugin registration. - ### P1: Recent `verify` Runs Behavior Now Has Regression Tests **Completed:** diff --git a/README.md b/README.md index e15dc09..1e36ded 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,7 @@ const app = await createFastify({ These reflect current implementation behavior. All are actively tracked for improvement. - **Route discovery requires ordering.** If the APOPHIS plugin or route discovery hook is not installed before routes are registered, behavioral contract annotations (x-ensures, x-requires, x-outbound, x-variants, x-timeout) cannot be recovered. Use `createFastify()` for new projects or register APOPHIS early. -- **Observe has two faces.** The runtime plugin supports non-blocking sink emission via `observe.enabled` + `observe.sinks` when registered programmatically. `apophis observe` CLI validates config readiness; it does not activate a long-running runtime observer. See `docs/observe.md` for the distinction between programmatic runtime observation and CLI config validation. +- **Observe is programmatic.** Register `apophisPlugin` with `observe: { enabled: true, sinks: [...] }` for non-blocking contract evaluation on live traffic. Use `apophis doctor --mode observe` to validate config before deploying. See `docs/observe.md`. - **CLI verify samples once per contract by default.** Set `runs` in your preset to increase the number of property-based test samples per route. The programmatic `fastify.apophis.contract()` API supports the same `runs` configuration. - **Outbound mocks are process-global.** The mock runtime patches `globalThis.fetch`. Only one mock runtime can be installed at a time. Run mock-dependent tests serially or isolate by process. Undici `MockAgent` integration is not yet implemented. - **Qualify coverage depends on profile configuration.** Qualify runs scenario, stateful, and chaos checks based on profile gates. Chaos route selection uses the configured strategy (one/all/sample/routes). diff --git a/docs/cli.md b/docs/cli.md index c306ac8..f925e03 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -85,26 +85,6 @@ apophis verify --profile quick --format json-summary apophis verify --profile quick --format ndjson-summary ``` -### `apophis observe` - -Validate runtime observe configuration and reporting setup. - -```bash -apophis observe --profile staging-observe -``` - -| Flag | Description | -|---|---| -| `--profile ` | Profile name from config | -| `--check-config` | Only validate config, do not activate | - -**Examples:** - -```bash - -apophis observe --help -``` - ### `apophis qualify` Run scenario, stateful, protocol, or chaos-driven qualification. diff --git a/docs/observe.md b/docs/observe.md index 1642ee5..6bf241a 100644 --- a/docs/observe.md +++ b/docs/observe.md @@ -2,11 +2,9 @@ Runtime visibility and drift detection without blocking by default. -APOPHIS observe has two paths: +APOPHIS observe is **programmatic only**. Register the APOPHIS plugin with `observe.enabled: true` and `observe.sinks` to emit contract pass/violation/error events from live traffic without blocking responses. Sampling controls the fraction of observed requests. -1. **CLI `apophis observe`**: Validates observe configuration readiness (policy, sinks, sampling, safety boundaries). Introduces no service process or runtime hooks. Use this for CI config validation before deployment. - -2. **Programmatic runtime observation**: Register the APOPHIS plugin with `observe.enabled: true` and `observe.sinks` to emit contract pass/violation/error events from live traffic without blocking responses. Sampling controls the fraction of observed requests. +Use `apophis doctor --mode observe` to validate your observe configuration (sinks, sampling, blocking, production safety) before deploying. ## When to Use It @@ -95,15 +93,9 @@ profiles: { } ``` -## `--check-config` Flag +## Config Validation -Validate config without activating observe mode: - -```bash -apophis observe --profile staging-observe --check-config -``` - -This is useful in CI to ensure observe config is valid before deployment. +Validate your observe config before deployment with doctor: ## Exit Codes @@ -161,10 +153,7 @@ export default { ## Programmatic Runtime Activation -The CLI only validates configuration. To activate runtime observation, register -APOPHIS with observe options in your application before routes are registered. -Observe remains active in production because it is non-blocking; blocking -runtime validation still stays disabled in production. +Register APOPHIS with observe options in your application before routes are registered. ```typescript import Fastify from 'fastify' @@ -248,9 +237,9 @@ plug in any backend. Common patterns: ## Monorepo Validation -For monorepos, use `apophis doctor --workspace` to validate observe configuration across all workspace packages. `observe` itself does not support `--workspace`; use `doctor` to check config in each package. +For monorepos, use `apophis doctor --mode observe --workspace` to validate observe configuration across all workspace packages. ## Mode Mismatch -Profiles configured for `verify` mode will be rejected by `apophis observe`. Only profiles with `mode: 'observe'` are valid. +Profiles configured for `verify` mode will be rejected at runtime. Only profiles with `mode: 'observe'` are valid for observe mode. ``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 48eb4f4..7ad80de 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -139,7 +139,7 @@ APOPHIS classifies failures into six categories. Lower categories take precedenc **Prevention** - Use `apophis verify --seed ` for deterministic runs. -- Run `apophis observe` in CI to catch drift before it becomes a failure. +- Run `apophis doctor --mode observe` in CI to catch config drift before deployment. - Keep test data isolated and reset between runs. ---