fix: harden trace context propagation and collector ingest

addons/observability/observability.go

@@ -3,6 +3,8 @@
 package observability
 
 import (
+	"time"
+
 	"github.com/cssbruno/gowdk"
 	gowdktrace "github.com/cssbruno/gowdk/runtime/trace"
 )
@@ -21,9 +23,22 @@ func Addon() gowdk.Addon {
 	return gowdk.NewAddon("observability", gowdk.FeatureObservability)
 }
 
+// CollectorOption configures a Collector.
+type CollectorOption = gowdktrace.CollectorOption
+
 // NewCollector creates a bounded in-memory trace collector.
-func NewCollector(limit int) *Collector {
-	return gowdktrace.NewCollector(limit)
+func NewCollector(limit int, options ...CollectorOption) *Collector {
+	return gowdktrace.NewCollector(limit, options...)
+}
+
+// WithCollectorSSELimit configures the collector's concurrent SSE stream cap.
+func WithCollectorSSELimit(limit int) CollectorOption {
+	return gowdktrace.WithCollectorSSELimit(limit)
+}
+
+// WithCollectorIngestRate configures the collector's per-client POST rate.
+func WithCollectorIngestRate(limit int, window time.Duration) CollectorOption {
+	return gowdktrace.WithCollectorIngestRate(limit, window)
 }
 
 // NewTracer creates a dependency-free tracer.

docs/engineering/architecture.md

@@ -65,13 +65,13 @@ nacked-batch backoff options while adapters retain durable retry and
 dead-letter policy ownership.
 
 `runtime/trace` provides the first dependency-free GOWDK Trace core. It owns
-W3C-compatible trace/span IDs, `traceparent` propagation, context spans,
+W3C-compatible trace/span IDs, bounded `traceparent`/`tracestate` propagation, context spans,
 GOWDK surface/lane/source metadata, attributes, events, status, sampling,
 console/JSONL/ring/multi/exporter sinks, and a bounded in-process JSON/SSE
-collector. Generated app auto-instrumentation, durable storage, a browser trace
-viewer, and concrete OTLP transport are later integration work. Debug-gated
-generated instrumentation now covers backend, SSR/load, contract, browser, and
-island lanes through `addons/observability`.
+collector with hardened browser ingest. Durable storage and concrete production
+telemetry backends are app-owned integration work. Debug-gated generated
+instrumentation now covers backend, SSR/load, contract, browser, and island
+lanes through `addons/observability`.
 
 Still partial: broad local client-side reactivity, richer hybrid streaming and
 data refresh, non-HTTP revalidation, generated worker/cron binary scaffolding,
@@ -209,7 +209,7 @@ manifest report (`internal/lang/testdata/manifest_golden`).
 | `runtime/security` | Runtime-safe security text helpers. | Runtime | Provides conservative secret-like text redaction for generated app panic/error logging without importing compiler-private `internal/` packages. |
 | `runtime/testkit` | Generated audit test helpers. | Runtime | Provides small `httptest` helpers used by generated `gowdk_audit_test.go` files and `gowdk audit --run` to verify route status, method rejection, and configured response headers in-process against generated app handlers. |
 | `runtime/contracts` | Typed contract registry and in-process dispatch. | Runtime | Implemented for queries, commands, backend-owned domain and integration events, presentation events, jobs, metadata, stable observation names and labels for logs/metrics/traces, local command-buffered event dispatch, event-envelope capture/replay with stable IDs, dependency-free outbox/broker/presentation-fanout/event-source/seen-store interfaces, command event sinks, an event worker loop with ack/nack, context cancellation, optional post-ack deduplication windows, explicit nacked-batch backoff options, a dependency-free file outbox adapter, dependency-free in-memory broker/EventSource adapter, dependency-free in-memory and file-backed seen stores, and dependency-free SSE presentation fanout adapter with retry hints and drop-on-full per-client buffers. Concrete Redis Streams, Redis TTL seen-store, NATS, and WebSocket adapters are nested optional modules. Separate worker/cron binary generators and deployment recipes are platform tooling, not runtime core. |
-| `runtime/trace` | Dependency-free runtime tracing core. | Runtime | Provides W3C-compatible trace/span IDs, `traceparent` inject/extract helpers, context spans, GOWDK surface/lane/source metadata, attributes, events, status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, OTLP-shaped snapshots without an OpenTelemetry dependency, and a bounded JSON/SSE collector. Generated backend, SSR/load, guard, contract, browser, and island instrumentation is opt-in and debug-gated through `addons/observability`; durable trace storage and production sampling/access policy remain app-owned. |
+| `runtime/trace` | Dependency-free runtime tracing core. | Runtime | Provides W3C-compatible trace/span IDs, bounded `traceparent`/`tracestate` inject/extract helpers, context spans, GOWDK surface/lane/source metadata, attributes, events, status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, OTLP-shaped snapshots without an OpenTelemetry dependency, and a bounded JSON/SSE collector with hardened browser ingest. Generated backend, SSR/load, guard, contract, browser, and island instrumentation is opt-in and debug-gated through `addons/observability`; durable trace storage and production sampling/access policy remain app-owned. |
 | `runtime/actions` | Request-time action helpers. | Runtime | Owns CSRF token validation/generation, generated action registries, form decoding, and required-field validation helpers. |
 | `runtime/api` | Request-time API helpers. | Runtime | Owns strict JSON request decoding, query helpers, and JSON/error/no-content response helpers. |
 | `runtime/partial` | Request-time partial update helpers. | Runtime | Owns fragment responses, swap helpers, and partial client hook constants. |

docs/product/requirements.md

@@ -55,7 +55,7 @@ language references, compiler docs, and examples.
 | PRD-027 | Provide opt-in browser presentation-event fanout without adding WebSocket dependencies to the root module. | Medium | Implemented | `FeatureRealtime` and `addons/realtime` provide config and `gowdk add realtime` wiring for presentation-event fanout. Dependency-free SSE fanout remains in the root module through `runtime/contracts/sse` and `realtime.NewSSE`; WebSocket fanout remains isolated in the nested `runtime/contracts/websocketfanout` module. Docs cover SSE versus WebSocket setup, deployment caveats, and the M14 boundary for live DOM reactivity. |
 | PRD-028 | Provide compiler-validated realtime UI subscription metadata. | Medium | Partial | ADR 0012 defines `g:subscribe` on query-owned elements. The compiler parses the directive, lowers it to `Program.RealtimeSubscriptions`, requires `realtime.Addon()`, validates referenced Go contracts as presentation events available to the web role, emits exact-span diagnostics, renders `data-gowdk-subscribe` and validated `data-gowdk-subscribe-type` markers, records build-report metadata, generated apps mount subscription-filtered SSE fanout at `/_gowdk/realtime/events` for bound subscriptions, generated stream handlers run inherited guards before opening SSE responses, the SSE adapter declares browser retry timing and drops events for full per-client buffers instead of blocking command execution, generated `gowdk.js` applies explicit `replaceHTML` realtime patches to subscribed query regions, and `examples/contracts` demonstrates the live flow. The compiler also scans explicit Go `RegisterInvalidation[event, query]` edges, lowers validated bound edges to `Program.QueryInvalidations`, rejects unknown queries/events or events no scanned command emits, records `query_invalidation` build-report events, prints `invalidates` graph edges, renders `data-gowdk-query-type` markers, emits generated `gowdk.query.invalidate` presentation events after command event dispatch, and refetches the current document to replace matching non-subscribed query regions. Custom retry/backoff/replay, active session-change stream revocation, richer patch shapes, fragment/API-specific query execution, and route-specific refresh endpoints remain planned hardening work. |
 | PRD-029 | Provide optional SEO build output for sitemap and robots files without making crawler policy core. | Medium | Partial | `addons/seo` registers `FeatureSEO` and `gowdk.SEOProvider`; `gowdk build` emits `sitemap.xml` and `robots.txt` only when the addon supplies a valid `BaseURL`. The sitemap includes public static and `paths {}`-expanded SPA routes plus configured extra URLs, while request-time and guardless default-denied pages are excluded and listed in `gowdk-build-report.json`. JSON-LD and request-time sitemap serving remain planned/out of scope for this slice. |
-| PRD-030 | Provide dependency-free runtime trace primitives and opt-in generated app instrumentation. | Medium | Partial | ADR 0013 defines `runtime/trace` as the root-module observability core. It provides W3C-compatible trace/span IDs, `traceparent` propagation, context spans, GOWDK surface/lane/source metadata, attributes/events/status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, a bounded JSON/SSE collector, browser span ingest, and a self-contained local viewer. `addons/observability` gates debug-only generated route/guard/handler/SSR-load/browser/island tracing, `runtime/contracts` propagates trace context through events/jobs/workers/outbox records, and the nested `runtime/trace/otel` module provides optional OTLP HTTP export without root OpenTelemetry dependencies. Durable production storage, hosted analysis, and production sampling/access policy remain app-owned. |
+| PRD-030 | Provide dependency-free runtime trace primitives and opt-in generated app instrumentation. | Medium | Partial | ADR 0013 defines `runtime/trace` as the root-module observability core. It provides W3C-compatible trace/span IDs, `traceparent`/`tracestate` propagation with bounded header parsing, context spans, GOWDK surface/lane/source metadata, attributes/events/status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, a bounded JSON/SSE collector, hardened browser span ingest, and a self-contained local viewer with dropped/rejected counters. `addons/observability` gates debug-only generated route/guard/handler/SSR-load/browser/island tracing, `runtime/contracts` propagates trace context through events/jobs/workers/outbox records, and the nested `runtime/trace/otel` module provides optional OTLP HTTP export without root OpenTelemetry dependencies. Durable production storage, hosted analysis, and production sampling/access policy remain app-owned. |
 | PRD-031 | Provide a config-owned localization contract for generated page routes and typed message catalogs. | Medium | Partial | `Config.I18N` declares locale codes, optional path prefixes, default locale, and default-prefix omission. Build-time SPA routes, dynamic `paths {}` output, request-time SSR/hybrid page routes, route metadata, site-map JSON, route manifests, and SEO sitemap output expand per locale. Build helpers receive `gowdk.BuildParams.Locale`, generated HTML receives `lang`, SSR handlers attach `runtime/app.Locale(ctx)`, and `runtime/i18n` provides typed Go catalog/bundle helpers. Message extraction, ICU/plural/date formatting, translated diagnostics, and per-endpoint locale policies remain planned or app-owned. |
 
 ## P0/P1/P2 Decision Backlog
@@ -82,7 +82,7 @@ implemented.
 | Forms | Keep progressive-enhancement-first form behavior; full POST and enhanced POST share action result semantics; domain validation stays in user Go. | Partial | Generated enhanced forms preserve no-JavaScript POST behavior, send partial request headers, swap server fragments, expose failed enhanced response status/body/detail events, and use escaped live-region validation fragments. Domain validation stays in user Go. |
 | APIs | Broaden APIs through public request/response helpers and typed body/query helpers, not framework-specific adapters. | Partial — `addons/api` provides strict JSON body decoding, typed query helpers, JSON/error/no-content response helpers for current `func(context.Context, *http.Request) (response.Response, error)` handlers, and config-level CORS policy for generated API/command/query routes. Generated typed handler signatures, per-route result contracts, per-endpoint CORS syntax, and richer examples remain planned. |
 | Contract runtime | Add typed Go queries, commands, backend-owned domain/integration events, presentation events, and jobs after endpoint/adapter IR is stable. Frontend UI events trigger commands or queries, commands have one owner, domain events are emitted after backend state changes succeed, local in-process dispatch is default, and broker/outbox/worker roles are optional. Runtime registry, role filtering, event capture/replay, outbox/broker/fanout/EventSource/seen-store interfaces, worker ack/nack/backoff, file/in-memory/Redis/NATS adapters, SSE/WebSocket fanout, generated command event sinks, generated registries, generated worker replay helpers, Go AST scanning, `go/types` diagnostics, duplicate-owner and emitted-event diagnostics, contract/list/graph/trace CLI, `g:command`/`g:query` metadata, query-bounded `g:subscribe`, explicit `RegisterInvalidation[event, query]` metadata, import-path-aware reference/subscription/invalidation linking, `g:event` rejection, IR binding status, app adapter IR, generated web command/query adapters, page-route query JSON negotiation, stable JSON success/error response shape, formatted generated adapter source, page-guard propagation, rate-limit/guard/CSRF ordering, report metadata, enforced scan diagnostics, generated subscription-filtered guarded SSE fanout, generated client `replaceHTML` patches, generated `gowdk.query.invalidate` events, and current-document refresh for matching non-subscribed invalidated query regions are implemented. Separate worker/cron binary generators, fragment/API-specific query execution, remaining exact diagnostic spans, richer realtime patch shapes, durable retry operations, and editor-first visualizations remain planned outside the milestone-14 runtime contract. | Implemented |
-| Observability | Keep root tracing dependency-free while making generated instrumentation opt-in and debug-gated. | Partial — `runtime/trace` provides W3C-compatible IDs, `traceparent` propagation, context spans, GOWDK surface/lane/source metadata, span attributes/events/status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, OTLP-shaped snapshots, bounded JSON/SSE local collection, browser ingest, and a self-contained viewer. `addons/observability` enables debug-only generated backend, SSR/load, frontend, and island tracing; contracts/outbox records carry optional trace context; `runtime/trace/otel` isolates OTLP HTTP export in a nested module. Durable storage, hosted analysis, and production sampling/access policy remain app-owned. |
+| Observability | Keep root tracing dependency-free while making generated instrumentation opt-in and debug-gated. | Partial — `runtime/trace` provides W3C-compatible IDs, bounded `traceparent`/`tracestate` propagation, context spans, GOWDK surface/lane/source metadata, span attributes/events/status, always-on/off and ratio sampling, console/JSONL/ring/multi/exporter sinks, OTLP-shaped snapshots, bounded JSON/SSE local collection, hardened browser ingest, and a self-contained viewer. `addons/observability` enables debug-only generated backend, SSR/load, frontend, and island tracing; contracts/outbox records carry optional trace context; `runtime/trace/otel` isolates OTLP HTTP export in a nested module. Durable storage, hosted analysis, full metrics/log correlation, and production sampling/access policy remain app-owned or future work. |
 | Cache | Keep `cache` and `revalidate` as HTTP cache policy; keep action-driven data refresh explicit through redirects, fragments, JSON, or reload responses. | Partial — route reports include route/endpoint cache metadata, build reports summarize generated cache policies, generated binaries apply immutable asset cache, SPA `no-cache`, request-time `no-store`, and page `cache`/`revalidate` for successful SPA/SSR HTML. |
 | Guards | Extend guards with safe local redirects and response helpers before richer request-local state. | Partial — guards keep the `func(runtime/guard.Context) error` signature. Ordinary errors fail closed with 403, while `runtime/guard.RedirectTo`, `runtime/guard.Redirect`, and `runtime/guard.Respond` intentionally write no-store redirects or custom responses. Richer request-local state is still deferred. |
 | Component CSS | Make component CSS explicit, compiler-scoped, and documented; Tailwind and processors remain optional. | Partial |