@glasstrace/sdk 1.6.1 → 1.8.0

package/README.md

@@ -83,7 +83,7 @@ init-hang cannot leave your installation in a broken state.
 | Exit code | Meaning |
 |-----------|---------|
 | `0` | Scaffolding succeeded AND the server confirmed the anon key. |
-| `1` | Scaffolding failed. No verification attempted. |
+| `1` | Scaffolding failed, OR the static-discovery file at `public/.well-known/glasstrace.json` could not be written. The browser extension cannot discover the project until that file is written; rerun `glasstrace init` after fixing the underlying error (most commonly: the static root is missing or read-only). |
 | `2` | Scaffolding succeeded but server verification failed. Safe to re-run. |
 
 On a non-zero verification exit, the error message distinguishes three
@@ -98,6 +98,18 @@ total cap). HTTP 4xx/5xx and malformed responses are surfaced
 immediately. Set `GLASSTRACE_SKIP_INIT_VERIFY=1` to skip verification
 for offline installs.
 
+## Getting help
+
+```bash
+glasstrace --help        # or: glasstrace -h
+glasstrace init --help   # same; help short-circuits subcommand routing
+```
+
+Help invocations print the command list and exit cleanly without
+modifying the project. Help is detected anywhere in the argv slice,
+including composite invocations like `glasstrace init --yes --help`
+(the `--yes` is ignored — the user asked for help).
+
 ## Refreshing agent instruction guidance
 
 `glasstrace init` and `glasstrace mcp add` write a managed Glasstrace

package/dist/{capture-error-BmQz7xF6.d.cts → capture-error-C95zvSvF.d.cts}

@@ -190,7 +190,40 @@ declare class GlasstraceExporter implements SpanExporter {
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
+    /**
+     * Lazily-bound reference to the export-path circuit breaker
+     * (DISC-1568 / Wave 15C). Resolved on first export so this
+     * constructor stays side-effect-free. The breaker is a module-
+     * singleton — every `GlasstraceExporter` instance shares the same
+     * one so a rotation event observed in `init-client.ts` reaches
+     * every active exporter.
+     */
+    private circuitBreaker;
     constructor(options: GlasstraceExporterOptions);
+    /**
+     * Returns the export-path circuit breaker, lazily wiring it on
+     * first call. The breaker is a module-singleton so all exporter
+     * instances share state — a credential rotation observed once
+     * resets the breaker for every active exporter, and a single
+     * outage at the OTLP endpoint trips a single breaker rather than
+     * one per exporter copy.
+     *
+     * The wiring binds:
+     * - the lifecycle event sink to the SDK's lifecycle bus
+     *   (`emitLifecycleEvent`) so the `otel:circuit_*` events surface
+     *   to runtime-state, the CLI bridge, and any user-installed
+     *   subscribers.
+     * - the dropped-span counter to {@link recordSpansDropped} so OPEN-
+     *   state drops show up in the existing health surface.
+     * - the FSM hooks to {@link pushDegradationSource} /
+     *   {@link clearDegradationSource} keyed on `"export-circuit"`,
+     *   which routes the OPEN/CLOSED transitions through the
+     *   centralised `recomputeCoreFromDegradationSources()` helper.
+     *   That helper guards `ACTIVE ↔ ACTIVE_DEGRADED` so a circuit
+     *   recovery never clobbers an unrelated `OtelState.COEXISTENCE_FAILED`
+     *   degradation source.
+     */
+    private getCircuitBreaker;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * Called when the API key transitions from "pending" to a resolved value.
@@ -234,6 +267,11 @@ declare class GlasstraceExporter implements SpanExporter {
      * Flushes all buffered spans through the delegate exporter.
      * Enriches spans at flush time (not buffer time) so that session IDs
      * are computed with the resolved API key instead of the "pending" sentinel.
+     *
+     * Honors the circuit breaker symmetrically with {@link export}: if the
+     * breaker is OPEN at flush time, every buffered batch is dropped via
+     * `recordSpansDropped` and its callback completed with `{ code: 0 }`,
+     * preserving the bounded-memory contract during outages.
      */
     private flushPending;
 }

package/dist/{capture-error-CTgSYxek.d.ts → capture-error-Dzz7_-v4.d.ts}

@@ -190,7 +190,40 @@ declare class GlasstraceExporter implements SpanExporter {
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
+    /**
+     * Lazily-bound reference to the export-path circuit breaker
+     * (DISC-1568 / Wave 15C). Resolved on first export so this
+     * constructor stays side-effect-free. The breaker is a module-
+     * singleton — every `GlasstraceExporter` instance shares the same
+     * one so a rotation event observed in `init-client.ts` reaches
+     * every active exporter.
+     */
+    private circuitBreaker;
     constructor(options: GlasstraceExporterOptions);
+    /**
+     * Returns the export-path circuit breaker, lazily wiring it on
+     * first call. The breaker is a module-singleton so all exporter
+     * instances share state — a credential rotation observed once
+     * resets the breaker for every active exporter, and a single
+     * outage at the OTLP endpoint trips a single breaker rather than
+     * one per exporter copy.
+     *
+     * The wiring binds:
+     * - the lifecycle event sink to the SDK's lifecycle bus
+     *   (`emitLifecycleEvent`) so the `otel:circuit_*` events surface
+     *   to runtime-state, the CLI bridge, and any user-installed
+     *   subscribers.
+     * - the dropped-span counter to {@link recordSpansDropped} so OPEN-
+     *   state drops show up in the existing health surface.
+     * - the FSM hooks to {@link pushDegradationSource} /
+     *   {@link clearDegradationSource} keyed on `"export-circuit"`,
+     *   which routes the OPEN/CLOSED transitions through the
+     *   centralised `recomputeCoreFromDegradationSources()` helper.
+     *   That helper guards `ACTIVE ↔ ACTIVE_DEGRADED` so a circuit
+     *   recovery never clobbers an unrelated `OtelState.COEXISTENCE_FAILED`
+     *   degradation source.
+     */
+    private getCircuitBreaker;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * Called when the API key transitions from "pending" to a resolved value.
@@ -234,6 +267,11 @@ declare class GlasstraceExporter implements SpanExporter {
      * Flushes all buffered spans through the delegate exporter.
      * Enriches spans at flush time (not buffer time) so that session IDs
      * are computed with the resolved API key instead of the "pending" sentinel.
+     *
+     * Honors the circuit breaker symmetrically with {@link export}: if the
+     * breaker is OPEN at flush time, every buffered batch is dropped via
+     * `recordSpansDropped` and its callback completed with `{ code: 0 }`,
+     * preserving the bounded-memory contract during outages.
      */
     private flushPending;
 }