alkhttp/tasks/adapters/review-002-fwd17-19-contract-decisions.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-002-fwd17-19-contract-decisions	Forwarding contract decisions — non-JSON SSE payloads, double-routed placeholders, percent preservation (FWD-17/18/19 decide+document or fix)	completed	review-002-fwd15-stream-timeout	narrow	low	component	implementation	adapters review-002 from-openapi

Description

Three review-002 forwarding findings that are design decisions more than bugs — decide, document, and fix where the decision says so:

• FWD-17: non-JSON SSE payloads silently degrade to JSON strings (forward.rs:774-781, unwrap_or(Value::String)) and the parser's event: field is discarded (:977-979). A consumer cannot extract fields from a legitimately non-JSON stream, and an upstream's SSE event: error convention is indistinguishable from data. Decide: (a) document the JSON-or-string contract as-is, or (b) carry the raw payload + the event: field name in the envelope for non-JSON payloads (e.g. {data, event} object wrapper).
• FWD-18: non-scalar path-placeholder values double-route — rendered into the path (as JSON text) and appended as a query param (forward.rs:144-157). Fix the routing rule: a key that matched a placeholder never also emits as query, regardless of value shape (plus a spec-decision on whether object/array path values are an error instead).
• FWD-19 [info]: preserved literal % in template/base text is upstream-semantics-changing (%2F survives; most stacks route it differently from /). Inputs are assembly-supplied (ADR-066 trust); document the trade-off in the module doc (+ ADR-066 note) — or reject raw % in template text while allowing it in values (the strict shape).

Acceptance Criteria

• A decision per finding, recorded (module doc + ADR-066 section as appropriate); doc-only outcomes still need the doc change + a doc-asserting test where applicable
• FWD-17: whichever shape is chosen, non-JSON payload behavior is pinned by a test (string case, number-vs-string distinction, event-field presence if option (b))
• FWD-18: placeholder keys never double-emit (query test with an object value under a placeholder key) — and the object-in-path outcome (error vs JSON-segment) decided and tested
• FWD-19: documented (and if the reject-raw-% shape is chosen, its import- or call-time error tested)
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass

References

• docs/reviews/002-post-remediation-review.md (Part D', FWD-17/18/19)
• src/adapters/forward.rs:774-781, :977-979, :144-157, :353-370, :481-505
• docs/architecture/decisions/066-from-jsonschema-as-http-adapter.md
• tasks/adapters/review-002-fwd13-dot-segments.md (adjacent template-renderer work — sequence or coordinate to avoid churn in the same helpers)

Notes

Deliberately a decide-first task: none of the three is a crash or leak; each is a contract the code half-implies. Keep the decisions small and documented rather than building speculative machinery (e.g. no new envelope schema unless (b) is actually chosen). Coordinate with review-002-fwd13-dot-segments (same helpers, different concerns).

Summary

FWD-17: non-JSON SSE payloads surface as {data, event} wrapper (event: captured, WHATWG last-wins, leak fixed). FWD-18: structural placeholder values are INVALID_INPUT (no JSON splicing into paths). FWD-19: % in values always encoded, template text preserves pre-encoded % (ADR-066 trust boundary). ADR-066 records all three; SseEvent gained an event field (crate-internal).