feat(contracts): complete local web adapter path

CHANGELOG.md

@@ -41,23 +41,26 @@ packages, and tooling contracts may change before a stable release.
   source; a sibling Go package that fails to compile keeps a "could not be
   inspected" binding instead of falling back to an inline block and reporting a
   misleading bound handler (the compile error is reported by `go_package_error`);
-  a failing `go list` for a same-package build function now surfaces its real
+  and a failing `go list` for a same-package build function now surfaces its real
   cause (for example a missing `go.mod`) rather than a generic "requires a
-  buildable Go package" message; and a component-script resolution error during
+  buildable Go package" message. A component-script resolution error during
   build now fails the build instead of silently omitting the page's component
-  scripts. The contract scanner's `go list -deps -export` failures now surface
-  their stderr instead of reaching the type checker as an opaque "exit status 1",
-  and an unknown build-data interpolation reference now reports whether the
-  missing name was a build-data field or a route param instead of always saying
-  "unknown route param". Generated-app module resolution no longer silently
-  drops the app module's `require`/`replace` when `go list -m` fails: if the
-  generated app imports app-owned packages it now fails with the real `go list`
-  error instead of producing a go.mod that fails to build with an opaque
-  "cannot find package".
-- The generated-app module loud-failure path is now covered by an integration
-  test: with `go list -m` unable to determine the main module, `moduleSource`
-  fails when the app imports app-owned packages and stays silent when it does
-  not, so the fail-loudly contract for app-module resolution is regression-proof.
+  scripts.
+- Generated `g:command` and `g:query` contract web adapters now use one JSON
+  response contract: success writes the command/query result as no-store JSON,
+  and failures write `{"error":"..."}` as no-store JSON with ordinary 5xx
+  details redacted unless the handler returns an explicit
+  `response.HandlerError`; command form parse, oversized body, CSRF, and input
+  decode failures use the same JSON error shape.
+- Contract event envelopes now carry stable IDs for durable delivery. Workers
+  can opt into deduplication with `RunEventWorkerWithSeenStore` or
+  `RunEventWorkerForRoleWithSeenStore`; duplicate IDs are acked without
+  subscriber dispatch inside the configured window, and fresh IDs are marked
+  seen only after dispatch and source ack succeed. Runtime includes bounded
+  in-memory, file-backed, and Redis TTL seen-store adapters. File outbox records
+  keep unique row IDs separate from event IDs, file-backed outbox/dead-letter
+  and seen-store updates use temp-file replacement, and NATS batch drains
+  preserve already-decoded events if a later drained message cannot be decoded.
 
 ### Known Gaps
 

docs/engineering/architecture.md

@@ -42,9 +42,11 @@ retry metadata and opt-in dead-letter storage. Runtime also includes in-memory
 broker/EventSource and SSE presentation fanout adapters in the root module.
 Concrete Redis Streams, NATS, and WebSocket adapters live as nested optional Go
 modules under `runtime/contracts` so those third-party clients do not enter the
-root module graph. Generated apps can expose contract event sink registration,
-fresh registry construction, and a worker replay helper for executable contract
-registrations. Split runtime binaries, retry backoff policy, and managed
+root module graph. Durable event envelopes carry stable IDs, workers can use
+in-memory, file-backed, or Redis seen stores to skip duplicates inside a
+post-ack deduplication window, and generated apps can expose contract event sink
+registration, fresh registry construction, and worker replay helpers for
+executable contract registrations. Split runtime binaries, retry backoff policy, and managed
 deployment recipes remain planned.
 
 Still partial: broad local client-side reactivity, richer hybrid streaming and
@@ -170,7 +172,7 @@ manifest report (`internal/lang/testdata/manifest_golden`).
 | `runtime/asset` | Asset manifest resolution. | Runtime | Initial manifest helper implemented. |
 | `runtime/route` | Runtime route matching for generated request-time routes. | Runtime | Dynamic route matcher for first-slice generated SSR routes implemented. |
 | `runtime/app` | Shared generated app HTTP server. | Runtime | Serves embedded spa files, identity headers, health checks, asset manifest counts, optional generated 404/500 pages, no-JS cookie acknowledgement, server-side cookie notice hiding, generated CSRF token injection for POST forms, request-time panic boundaries, and generated action/API/fragment/SSR callback hooks. |
-| `runtime/contracts` | Typed contract registry and in-process dispatch. | Runtime | First runtime slice 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, dependency-free outbox/broker/presentation-fanout/event-source interfaces, command event sinks, an event worker loop with ack/nack plus context cancellation, a dependency-free file outbox adapter, dependency-free in-memory broker/EventSource adapter, and dependency-free SSE presentation fanout adapter. Concrete Redis Streams, NATS, and WebSocket adapters are nested optional modules. Split worker/cron generation, retry backoff policy, and managed deployment recipes remain planned. |
+| `runtime/contracts` | Typed contract registry and in-process dispatch. | Runtime | First runtime slice 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 plus context cancellation and optional post-ack deduplication windows, 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. Concrete Redis Streams, Redis TTL seen-store, NATS, and WebSocket adapters are nested optional modules. Split worker/cron generation, retry backoff policy, and managed deployment recipes remain planned. |
 | `addons/static` | Build-time static page output. | Addon | Capability boundary implemented; build-time output uses `runtime/render` through the compiler view renderer. |
 | `addons/spa` | Static-first SPA navigation compatibility surface. | Addon | Keeps the existing SPA feature package and aliases build-time route output types from `addons/static`. |
 | `addons/actions` | Typed backend actions, form decoding, CSRF. | Addon | Capability boundary, generated request-shape validation for direct literal required/minlength/maxlength/pattern controls, escaped live-region validation fragments for partial requests, signed CSRF validator, and generated action CSRF wiring implemented; user-defined domain validation helpers remain planned. |

docs/product/requirements.md

@@ -74,7 +74,7 @@ implemented.
 | Inline Go authoring | Allow optional Go code blocks inside `.gwdk` only when they extract to normal importable, formatted, testable package Go. Separate `.go` files remain supported and generated adapters remain glue. Saved default `go {}` blocks are type-checked with sibling Go files during validation, default `go {}` blocks can provide build-time no-argument functions for `build { => LocalFunc() }` and same-page action/API/fragment handlers, page-level `go client {}` blocks can opt into client-side Go by exporting `GOWDKMount<PageID>` for generated WASM page mounts, generated app source materializes default `go {}` and `go ssr {}` blocks under `gowdk_go/`, `go ssr {}` can provide generated SSR load handlers, and configured addons implementing `gowdk.GoBlockConsumer` can validate `go addon.<name> {}` blocks and emit generated app Go files. Source-adjacent extraction and addon adapter contracts remain planned. | Partial |
 | 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, and JSON/error/no-content response helpers for current `func(context.Context, *http.Request) (response.Response, error)` handlers. Generated typed handler signatures, per-route result contracts, CORS policy, 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. First runtime registry, runtime role filtering helpers, event-envelope capture/replay, stable observation names and labels for logs/metrics/traces, dependency-free outbox, broker, presentation-fanout, and event-source interfaces, event worker loop with ack/nack and context cancellation, dependency-free file outbox adapter with retry metadata and opt-in dead-letter storage, dependency-free in-memory broker/EventSource adapter, Redis Streams broker/EventSource adapter, NATS broker/EventSource adapter, dependency-free SSE presentation fanout adapter, WebSocket presentation fanout adapter, generated command event sink registration, generated contract registry construction, generated worker replay helper, Go AST scanner, scan-local package inspection cache, local-package and imported-handler `go/types` diagnostics, local and imported contract/result type diagnostics, local exported struct/function contract diagnostics, duplicate command-owner scan diagnostics, generated-app import-cycle diagnostics, emitted-event category diagnostics, first browser-UI and vague event-name diagnostics, contract/list/graph/trace CLI, form-local `g:command` metadata with literal form method/action, element-local `g:query` metadata with page-route source metadata, import-path-aware command/query reference linking, `g:event` rejection, IR command/query references with exact source locations, command/query reference binding status, appgen adapter IR exposure metadata, command method/path adapter metadata, query page-route adapter metadata, generated web command/query adapters, page-route query JSON negotiation, AST/printer/format generated adapter source, page-guard propagation for generated command/query routes, rate-limit and guard preflight before contract execution, CSRF-before-command-decoding ordering, routes-report contract endpoint metadata, missing/invalid/non-web-role contract-reference diagnostics, enforced Go contract scan diagnostics in check/build, and build-report contract-reference events with role metadata are implemented; all diagnostic spans, fragment/API-specific query execution, split-binary worker/cron wiring, retry backoff policies, and managed deployment recipes remain planned. | Partial |
+| 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. First runtime registry, runtime role filtering helpers, event-envelope capture/replay with stable event IDs, stable observation names and labels for logs/metrics/traces, dependency-free outbox, broker, presentation-fanout, event-source, and seen-store interfaces, event worker loop with ack/nack, context cancellation, and optional post-ack deduplication windows, dependency-free file outbox adapter with retry metadata and opt-in dead-letter storage, dependency-free in-memory broker/EventSource adapter, dependency-free in-memory and file-backed seen stores, Redis Streams broker/EventSource adapter, Redis TTL seen store, NATS broker/EventSource adapter, dependency-free SSE presentation fanout adapter, WebSocket presentation fanout adapter, generated command event sink registration, generated contract registry construction, generated worker replay helper with optional seen-store dedup, Go AST scanner, scan-local package inspection cache, local-package and imported-handler `go/types` diagnostics, local and imported contract/result type diagnostics, local exported struct/function contract diagnostics, duplicate command-owner scan diagnostics, generated-app import-cycle diagnostics, emitted-event category diagnostics, first browser-UI and vague event-name diagnostics, contract/list/graph/trace CLI, form-local `g:command` metadata with literal form method/action, element-local `g:query` metadata with page-route source metadata, import-path-aware command/query reference linking, `g:event` rejection, IR command/query references with exact source locations, command/query reference binding status, appgen adapter IR exposure metadata, command method/path adapter metadata, query page-route adapter metadata, generated web command/query adapters, page-route query JSON negotiation, stable JSON success/error response shape, AST/printer/format generated adapter source, page-guard propagation for generated command/query routes, rate-limit and guard preflight before contract execution, CSRF-before-command-decoding ordering, routes-report contract endpoint metadata, missing/invalid/non-web-role contract-reference diagnostics, enforced Go contract scan diagnostics in check/build, and build-report contract-reference events with role metadata are implemented; all diagnostic spans, fragment/API-specific query execution, split-binary worker/cron wiring, retry backoff policies, and managed deployment recipes remain planned. | Partial |
 | Cache | Keep `cache` and `revalidate` as HTTP cache policy; keep action-driven data refresh explicit through redirects, fragments, JSON, or reload responses. | Partial |
 | Guards | Extend guards with safe local redirects and response helpers before richer request-local state. | Planned |
 | Component CSS | Make component CSS explicit, compiler-scoped, and documented; Tailwind and processors remain optional. | Partial |