observability: make telemetry export explicit opt-in

Default Star Server telemetry export to off, require an explicit deployment gate in addition to loading the observability addon, update hermetic coverage, and document the Biz/infra activation contract.

Author: lost-rob0t

doc/configuration.org

@@ -46,22 +46,27 @@ server process.
 
 ** Observability configuration
 
-Telemetry is OFF until the operator opts in from the init file:
+Telemetry export requires two explicit opt-ins:
+
+1. the deployment sets =STAR_OBSERVABILITY_ENABLED=true=; and
+2. the trusted init file loads the addon:
 
 #+begin_src lisp
 (load-addon :starintel-observability)
 #+end_src
 
-Loading the addon starts the exporter thread and wires the instrumented
-CouchDB transport. Without that line, no exporter thread, no queues, no
-ids, and no counters run; the application has no telemetry dependency. The
-env kill switch below still overrides everything.
+Loading the addon with the export gate disabled starts no exporter. Leaving the
+addon unloaded starts no exporter thread, queues, ids, or counters. Hosted
+StarIntel deployments render the export gate from
+=starintel.biz.observability.enable=, which defaults to false. This keeps both
+package installation and addon availability separate from consent to export
+telemetry.
 
 Observability env variables (read by the =star.observability= library):
 
 | Variable | Default | Meaning |
 |----------+---------+---------|
-| =STAR_OBSERVABILITY_ENABLED= | =true= | kill switch; =false= disables all export |
+| =STAR_OBSERVABILITY_ENABLED= | =false= | explicit export gate; set =true= to permit export when the addon is loaded |
 | =STAR_OBSERVABILITY_ENDPOINT= | =http://127.0.0.1:4318= | OTLP/HTTP collector endpoint (compose: =http://otelcol:4318=) |
 | =STAR_OBSERVABILITY_SIGNALS= | =logs,metrics,traces= | comma-separated signals to record |
 | =STAR_TRACE_SAMPLE_RATE= | =1.0= | SDK-side rate; the collector tail-samples authoritatively (5% baseline) |
@@ -121,10 +126,11 @@ as an environment variable.
 The initializer attaches =star:observability-lease-metrics-hook= to the
 store, so =starintel_lease_stale_writer_rejections_total=,
 =starintel_lease_conflicts_total= and =starintel_lease_acquisitions_total=
-flow whenever the observability addon is loaded. When Valkey is unreachable,
-lease operations degrade per the adapter's bounded retry contract: they
-return retryable =:backend-unavailable= / =:timeout= / =:outcome-unknown=
-outcomes within the caller's deadline instead of signaling.
+flow when the observability addon is loaded and the explicit export gate is
+enabled. When Valkey is unreachable, lease operations degrade per the adapter's
+bounded retry contract: they return retryable =:backend-unavailable= / =:timeout=
+/ =:outcome-unknown= outcomes within the caller's deadline instead of
+signaling.
 
 The init file can override any knob before runtime start (the environment is
 read only when the image loads):

doc/observability.org

@@ -25,13 +25,18 @@ OpenObserve client. OpenObserve stays replaceable.
 
 * CURRENT implementation
 
-** Telemetry lifecycle (opt-in via init file)
+** Telemetry lifecycle (explicit opt-in)
 
 - The addon is registered at gserver load (metadata only).
 - Nothing runs until the operator adds =(load-addon :starintel-observability)=
   to the trusted init file. Without it: no exporter thread, no queues, no
   ids, no counters (verified by the =disabled-addon-costs-nothing= test).
-- The env kill switch =STAR_OBSERVABILITY_ENABLED=false= overrides the addon.
+- Export is additionally fail-safe gated by =STAR_OBSERVABILITY_ENABLED=,
+  which defaults to =false=. The addon starts an exporter only when the value
+  is explicitly set to =true= (or another documented truthy value).
+- Hosted deployments get that explicit flag from the StarIntel Biz/infra
+  =starintel.biz.observability.enable= switch; loading the addon alone is not
+  consent to export telemetry.
 - =stop-runtime= is NOT wired to telemetry; the addon lifecycle owns
   start/stop, exactly like =starintel-bixby=.
 
@@ -80,7 +85,8 @@ CouchDB joins one distributed trace when each hop carries the header.
 =star.observability= is covered by =t/observability-test.lisp= (FiveAM,
 hermetic):
 
-- config: enabled by default; disabled addon costs nothing;
+- config: disabled by default; explicit truthy opt-in; disabled addon costs
+  nothing;
 - W3C traceparent round-trip + malformed rejection;
 - child context keeps trace id and records parent;
 - structural redaction incl. case-insensitive forbidden keys;
@@ -115,7 +121,7 @@ Run: =nix run .#star-unit-tests=.
 
 | Symptom | Check |
 |---------+-------|
-| No telemetry at the gateway | Was the addon loaded in init.lisp? Is =STAR_OBSERVABILITY_ENDPOINT= reachable (compose: =http://otelcol:4318=)? |
+| No telemetry at the gateway | Is =STAR_OBSERVABILITY_ENABLED=true=? Was the addon loaded in init.lisp? Is =STAR_OBSERVABILITY_ENDPOINT= reachable (compose: =http://otelcol:4318=)? |
 | Collector export 401 | Gateway ingest token rotated: re-run =openobserve-provision= on observe (infra side); the sidecar itself holds no credential |
 | Spans missing but logs present | =STAR_OBSERVABILITY_SIGNALS= contents; collector =tail_sampling= baseline (5%) |
-| Telemetry volume explosion | =STAR_ACTOR_DETAIL=, =STAR_PROLOG_DETAIL=, span budget test |
+| Telemetry volume explosion | =STAR_ACTOR_DETAIL=, =STAR_PROLOG_DETAIL=, span budget test |

source/observability/config.lisp

@@ -1,10 +1,11 @@
 (in-package :star.observability)
 
 (defparameter *observability-enabled*
-  (or (uiop:getenv "STAR_OBSERVABILITY_ENABLED") "true")
-  "Whether telemetry is exported. Enabled by default per the locked
-observability-slice decision; set STAR_OBSERVABILITY_ENABLED=false to disable.
-Disabled mode starts no exporter thread and performs no network I/O.")
+  (or (uiop:getenv "STAR_OBSERVABILITY_ENABLED") "false")
+  "Whether telemetry is exported. Disabled by default: hosted deployments
+must opt in explicitly (the StarIntel Biz/infra policy propagates
+STAR_OBSERVABILITY_ENABLED=true). Disabled mode starts no exporter thread and
+performs no network I/O.")
 
 (defparameter *observability-endpoint*
   (or (uiop:getenv "STAR_OBSERVABILITY_ENDPOINT")

t/observability-test.lisp

@@ -18,9 +18,16 @@
          (funcall thunk)
       (star.observability:reset-exporter-state))))
 
-(test config-enabled-by-default
-  "Telemetry is enabled by default per the locked slice decision."
-  (is (star.observability:observability-enabled-p)))
+(test config-disabled-by-default
+  "Telemetry requires an explicit deployment opt-in."
+  (let ((star.observability::*observability-enabled* "false"))
+    (is (not (star.observability:observability-enabled-p)))))
+
+(test config-explicit-opt-in
+  "The deployment gate accepts the documented truthy values."
+  (dolist (value '("1" "true" "yes" "on" "TRUE"))
+    (let ((star.observability::*observability-enabled* value))
+      (is (star.observability:observability-enabled-p)))))
 
 (test disabled-addon-costs-nothing
   "When the addon was never loaded (no exporter thread), the signal API is a