feat(realtime): wire query-bound live subscriptions

README.md

@@ -238,7 +238,7 @@ This table describes the current demoable 0.x slice. Status levels:
 | CSS/assets | Works, contract unstable | CSS processors, page CSS, scoped component CSS, component assets, asset manifests, content-hashed filenames, and optional Tailwind wrapper exist. | CSS processor contracts and optional dependency boundaries need hardening. | [CSS](docs/reference/css.md) | [CSS](examples/css/styled.page.gwdk) |
 | One-binary output | Works, contract unstable | `gowdk build --app --bin` can generate and compile an embedded Go server for supported SPA/backend/SSR slices. | Optional deployment generators and artifact smoke coverage are still expanding. | [Deployment](docs/reference/deployment.md) | [Embed](examples/embed/site.page.gwdk) |
 | Contracts | Works, contract unstable | Runtime contracts support typed queries, commands, events, jobs, role filtering, local dispatch, file outbox, broker/fanout adapters, contract graph/trace/list commands, and generated `g:command`/`g:query` web adapters. | Split worker/cron generation, retry policy, managed deployment recipes, and editor-first contract visualization remain planned. | [Contracts](docs/reference/contracts.md) | [Runtime contracts](runtime/contracts) |
-| Realtime | Works, contract unstable | `FeatureRealtime` and `addons/realtime` provide opt-in presentation-event fanout packaging, dependency-free SSE helpers, and nested WebSocket transport docs. | Live DOM reactivity and generated client bindings remain M14 work. | [Realtime](docs/reference/realtime.md) | [SSE](runtime/contracts/sse) |
+| Realtime | Works, contract unstable | `FeatureRealtime` and `addons/realtime` provide opt-in presentation-event fanout packaging, dependency-free SSE helpers, nested WebSocket transport docs, compiler-validated `g:subscribe` metadata, generated subscription-filtered guarded SSE fanout, bounded SSE retry/drop behavior, a bounded generated client patch loop for query-owned regions, and a live contracts example. | Custom retry/backoff/replay, active session-change stream revocation, richer patch shapes, and richer examples remain M14 work. | [Realtime](docs/reference/realtime.md) | [SSE](runtime/contracts/sse) |
 | Security audit | Early | `gowdk audit` derives an IR-backed posture for routes, endpoints, contracts, and frontend surface risks; evaluates the built-in baseline plus declared `*.audit.gwdk` policies; exits non-zero on error findings; can emit/run generated audit tests; and `gowdk build` writes the posture to a non-served report path. | The audit DSL and generated tests cover the M8 slice; broader auth/session ownership, richer role fixtures, and deeper browser/data-flow analysis remain app-owned or planned. | [Security](docs/engineering/security.md) | [Spec](docs/product/security-audit-spec.md) |
 | Dev server | Works | `gowdk dev` polls inputs, skips no-op rebuilds, serves or runs generated output, live-reloads browsers, shows a browser overlay with diagnostic codes/source spans/changed-file context, and keeps serving the last successful output. | Generated-app runtime browser overlay delivery and component HMR are intentionally deferred. | [Dev](docs/reference/dev.md) | [Getting started](docs/getting-started.md) |
 | Editor/LSP | Works | The VS Code extension and dependency-free LSP provide diagnostics, formatting, completions, hover, outline, semantic tokens, definitions, references, site-map visualization, project-aware navigation, and editor-visible `g:command`/`g:query` binding diagnostics for supported paths. | Richer quick fixes and route/endpoint/contract map polish are planned. | [Language server](docs/product/language-server.md) | [VS Code](editors/vscode) |

cmd/gowdk/build.go

@@ -196,7 +196,10 @@ func buildOnce(options cliOptions, request buildRequest, timings *buildTimingRec
 		}
 		contractReport = scanned
 		linkIRContractReferencesFromReport(&ir, contractReport)
-		return compiler.ValidateContractReferences(ir.ContractRefs)
+		if err := compiler.ValidateContractReferences(ir.ContractRefs); err != nil {
+			return err
+		}
+		return compiler.ValidateRealtimeSubscriptionBindings(ir.RealtimeSubscriptions)
 	}); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		var report compiler.ValidationErrors

cmd/gowdk/contracts.go

@@ -51,6 +51,9 @@ func linkIRContractReferencesFromReport(ir *gwdkir.Program, report contractscan.
 	if ir != nil && len(ir.ContractRefs) > 0 {
 		ir.ContractRefs = contractscan.LinkReferences(ir.ContractRefs, report)
 	}
+	if ir != nil && len(ir.RealtimeSubscriptions) > 0 {
+		ir.RealtimeSubscriptions = contractscan.LinkRealtimeSubscriptions(ir.RealtimeSubscriptions, report)
+	}
 }
 
 func validateContractScanReport(report contractscan.Report) error {

docs/compiler/build-report.md

@@ -60,6 +60,12 @@ Current report events include:
   `sourcemap`, `css`, or `asset`; `data.bytes` is the generated byte count.
   For `assets/gowdk/islands/wasm_exec.js`, `data.wasmExecGoVersion` records
   the Go toolchain version that supplied the runtime file.
+- `contract_reference`: one event per linked or unlinked `g:command`/`g:query`
+  reference, including owner, source, status, route metadata, roles, and
+  handler/register metadata when known.
+- `realtime_subscription`: one event per `g:subscribe` reference, including
+  query, presentation event, owner, source, status, roles, and handler/register
+  metadata when known.
 
 ## CLI Debug Output
 

docs/compiler/generated-output.md

@@ -63,6 +63,14 @@ Implemented today:
   fragments, SSR load functions, build-time Go calls, and web command/query
   references. `gowdk generate stubs` can write missing action/API handler
   stubs as normal Go code beside the owning source package.
+- Query-owned realtime subscription regions render `data-gowdk-query`,
+  `data-gowdk-subscribe`, and validated `data-gowdk-subscribe-type` markers
+  after `g:subscribe` validation. Generated apps mount
+  `/_gowdk/realtime/events`, expose `RealtimeEventsPath` and
+  `RegisterRealtimeFanout`, and dispatch command-emitted presentation events to
+  subscription-filtered SSE fanout. Generated `gowdk.js` connects subscribed
+  pages to the stream and applies explicit `replaceHTML` patches to the
+  matching query-owned region.
 - Generated apps pass one backend hook into `runtime/app.Handler`; generated
   action and API dispatch are internal details behind that hook.
 - Generated app creation auto-detects supported action endpoints and supported