chore: crush git history - reborn from consolidation on 2026-03-10

2026-03-10 00:00:00 -07:00
commit d278c4b105
313 changed files with 87549 additions and 0 deletions
@@ -0,0 +1,140 @@
+# Observe Mode
+
+Runtime visibility and drift detection without blocking by default.
+
+## What Observe Does
+
+`apophis observe` validates your runtime observe configuration:
+
+1. Checks that observe mode is allowed in the current environment
+2. Validates reporting sink setup (logs, metrics, traces)
+3. Confirms non-blocking semantics
+4. Reports what would be observed and why it is safe
+
+## When to Use It
+
+- **Staging**: Validate observe config before promoting to production
+- **Production**: Monitor contract drift without affecting requests
+- **Platform teams**: Centralized visibility across services
+
+## Safety Boundaries
+
+Observe mode is non-blocking by default:
+
+- **Non-blocking by default**: Contract violations are logged, not thrown
+- **No request failures in non-blocking mode**: Violations are reported instead of thrown
+- **Explicit opt-in for blocking**: Requires `allowBlocking: true` in environment policy
+- **Production gating**: Blocking behavior is blocked in production by default
+
+## Sink Configuration
+
+Observe mode requires a reporting sink. Configure it in your environment policy:
+
+```javascript
+environments: {
+  staging: {
+    name: 'staging',
+    allowVerify: true,
+    allowObserve: true,
+    allowQualify: false,
+    allowChaos: false,
+    allowBlocking: false,
+    requireSink: true
+  }
+}
+```
+
+APOPHIS supports these sink types:
+
+- **Logs**: Structured logging of contract violations
+- **Metrics**: Counter and histogram metrics for violation rates
+- **Traces**: Distributed tracing integration for violation context
+
+## Sampling
+
+Control observation overhead with sampling:
+
+```javascript
+profiles: {
+  'staging-observe': {
+    name: 'staging-observe',
+    mode: 'observe',
+    preset: 'platform-observe',
+    routes: []
+  }
+}
+```
+
+The `platform-observe` preset enables sampling at the preset level. Fine-tune per route with `x-observe-sampling` in your route schema.
+
+## Staging vs Production
+
+| Environment | Blocking | Sampling | Sink Required |
+|---|---|---|---|
+| Staging | No (default) | 10% | Yes |
+| Production | No (default) | 1% | Yes |
+
+## `--check-config` Flag
+
+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.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Observe config is valid and safe |
+| 2 | Safety violation or invalid config |
+
+## Config Example
+
+```javascript
+// apophis.config.js
+export default {
+  mode: 'observe',
+  profile: 'staging-observe',
+  profiles: {
+    'staging-observe': {
+      name: 'staging-observe',
+      mode: 'observe',
+      preset: 'platform-observe',
+      routes: []
+    }
+  },
+  presets: {
+    'platform-observe': {
+      name: 'platform-observe',
+      depth: 'standard',
+      timeout: 10000,
+      parallel: true,
+      chaos: false,
+      observe: true
+    }
+  },
+  environments: {
+    staging: {
+      name: 'staging',
+      allowVerify: true,
+      allowObserve: true,
+      allowQualify: false,
+      allowChaos: false,
+      allowBlocking: false,
+      requireSink: true
+    },
+    production: {
+      name: 'production',
+      allowVerify: true,
+      allowObserve: true,
+      allowQualify: false,
+      allowChaos: false,
+      allowBlocking: false,
+      requireSink: true
+    }
+  }
+};
+```