update specification

Author: dpaasman00

cmd/opampsupervisor/specification/README.md

@@ -223,6 +223,14 @@ telemetry:
   resource:
     service.namespace: otel-demo
 
+# Supervisor-side extensions. See "Supervisor Extensions" below.
+# Requires the `opampsupervisor.Extensions` feature gate (alpha).
+extensions:
+  # Single instance of an extension with default settings.
+  nop:
+  # Named instance with custom settings.
+  extension_a/primary:
+    option_a: value
 ```
 
 #### Notes on `agent::config_files`, `agent::args`, and `agent::env`
@@ -292,6 +300,50 @@ This results in the following Collector process invocation:
 ./otel-binary --config /var/lib/otelcol/supervisor/effective.yaml --feature-gates service.AllowNoPipelines
 ```
 
+### Supervisor Extensions
+
+Note: this capability is experimental and must be manually enabled via the
+`opampsupervisor.Extensions` feature gate (alpha, introduced in v0.151.0).
+If `extensions` are configured but the gate is disabled, the Supervisor
+will not start and the error message names the gate to enable.
+
+These are instances of extensions specific to the Supervisor and are 
+distinct from extensions configured inside the managed Collector's
+configuration. Supervisor extensions are loaded and managed by the 
+Supervisor process itself.
+
+Supervisor extensions are configured under a top-level `extensions:` key
+using the same `type` or `type/name` component ID form used by the
+Collector:
+
+```yaml
+extensions:
+  # Single instance, default settings.
+  nop:
+  # Named instance with custom settings.
+  some_extension/primary:
+    option_a: value
+```
+
+Only extensions present in the Supervisor's factory allowlist are
+supported. The allowlist is intentionally narrow and extensions are
+added on a case-by-case basis as their functionality is integrated.
+Referencing an unknown extension type, or providing invalid configuration
+for a known one, produces a startup error.
+
+#### Lifecycle
+
+1. On startup, each configured extension is parsed and validated
+   against its factory's config schema. Validation errors are reported
+   before any extension instance is created.
+2. Extensions are started in a deterministic order based on the
+   lexicographic ordering of their component IDs. If any extension
+   fails to start, previously started extensions are shut down in
+   reverse order before the failure is reported.
+3. On Supervisor shutdown, extensions are stopped in reverse start
+   order. Shutdown errors from individual extensions are aggregated
+   and reported together rather than aborting the shutdown sequence.
+
 ### Operation When OpAMP Server is Unavailable
 
 When the supervisor cannot connect to the OpAMP server, the collector will