E12 PR-2c: live WebChart HTTP transport (finalize against the real API contract)

[Taleef7]

Context

The final step of E12 (#184, epic closed; PR-2b merged 2026-07-03): make httpWebChartClient real against MIE's confirmed API. All pre-work: adapter core (engine/ingress/webchart/), enrollment roster (engine/ingress/enrollment/), offline dev-DB proof (#246), and the mock-contract transport (M1 Issue #255 — after it lands, this issue is request-shaping only).

What to do (when docs/MIE_INTEGRATION_QUESTIONS_2026-07-09.md section A is answered)

1. Diff the real contract against docs/WEBCHART_API_ASSUMPTIONS_2026-07.md; update the client's request shaping (endpoints/auth/paging) — variant (a) if FHIR, or add row→FHIR mapping per WEBCHART_FHIR_MAPPING.md §3 if proprietary.
2. Point the conformance suite at a recorded set of REAL responses (fixtures captured from the staging instance, PHI-free) — the dev-DB goldens remain the semantic baseline.
3. Wire behind resolveDataSource(env) (both WORKWELL_WEBCHART_* envs required; inert otherwise).
4. First live evaluation: a bounded population slice through evaluateSourceWithRoster, outcomes reviewed by owner BEFORE any persistence into a real run.

Acceptance criteria

• Client passes the conformance suite against recorded real responses
• Inert-unless-configured preserved (no envs ⇒ deployed behavior byte-identical; test)
• A live staging evaluation produces reviewed, plausible outcomes; per-patient failures isolate
• ADR recorded if the contract forces a design change; ARCHITECTURE/WEBCHART_FHIR_MAPPING updated
• pnpm typecheck && pnpm test green

How to verify

1. cd backend-ts && pnpm typecheck && pnpm test — must include the conformance suite passing against recorded real (PHI-free) responses, and a test proving no-envs-set ⇒ deployed behavior byte-identical (inert-unless-configured preserved).
2. Confirm a bounded live staging evaluation (via evaluateSourceWithRoster) produces reviewed, plausible outcomes, with per-patient failures isolated (never aborting the batch), and that the owner reviewed the outcomes BEFORE any persistence into a real run.
3. Confirm an ADR was recorded if the real contract forced a design change, and ARCHITECTURE.md / WEBCHART_FHIR_MAPPING.md are updated accordingly.

Effort & dependencies

Effort: days (post-M1-Issue-3). Dependencies: MIE answers A1–A8 (#254); #255 (M1 Issue 3, mock-contract transport pre-build).

Hard rules (repo-wide, non-negotiable)

• CQL Outcome Status is the SOLE compliance authority (ADR-008). Nothing you build may set, override, or shortcut it.
• Every state change writes an audit_events row. No exceptions.
• NO new npm dependencies unless the issue explicitly approves one; schema/DDL changes are owner-gated (Taleef only — stop and ask).
• Verify before claiming done: cd backend-ts && pnpm typecheck && pnpm test (expect ~1057+ pass / 1 pg-skip / 0 fail) and, if frontend touched, cd frontend && npm run lint && npm run build.
• Update affected docs (ARCHITECTURE/DATA_MODEL/MEASURES/DECISIONS/DEPLOY + JOURNAL.md entry) in the same PR. Conventional commits. Feature branch + PR; owner merges.

Links

• docs/ROADMAP_2026-07-09.md (lands in the roadmap docs PR)
• docs/WEBCHART_API_ASSUMPTIONS_2026-07.md
• docs/WEBCHART_FHIR_MAPPING.md §3
• docs/MIE_INTEGRATION_QUESTIONS_2026-07-09.md (section A)
• E12 — Pluggable data adapters: WebChart/SQL + DB-less JSON-bucket #184 (E12), E12 follow-up — WebChart dev-DB evaluation proof (offline PR-2c slice) #246 (dev-DB proof)

[Taleef7]

Scope update (2026-07-14): the transport itself is built — PR #288 (ADR-028) implemented the publicly verified contract (SMART Backend Services RS384 private_key_jwt, per-resource ?patient= composition since the real CapabilityStatement exposes no $everything, page-boundary dedupe, off-origin guard). What remains on this issue is only the MIE-gated residual: a registered backend-services client (JWKS attached) or RFC 7591 enabled on the sandbox, plus confirmation of pagination semantics and the granted scope form (system/*.rs vs system/*.read) — then a live-practice smoke and closing. See docs/INTEGRATION_RESEARCH_2026-07-13.md + the updated #254 package.