Plan 53 — Add 'role: context' flag for context streams (foundation slice)

[perki]

Phase A foundation of HDS Plan 53 — "Handle 'context' streams across webapp settings tree, hds-lib-js, hds-forms-js."

Background

Some streams in the data-model exist purely as descendant-streamId markers for the D3 context-via-substream resolution mechanic (Plan 46). They don't carry data themselves — they qualify events placed at the descendant with sub-domain context (e.g. fertility-specific treatment / procedure events).

Today these context streams are visually indistinguishable from data-bearing streams in the webapp settings tree, leading to confusion: users may expect to drop events directly onto them.

What this slice does (Phase A — data-model + hds-lib-js)

data-model

• New optional role field on stream definitions. v1 value: context.
• treatment-fertility and procedure-fertility tagged role: context.
• Field flows through dist/streamsTree.json and pack.json (parsed YAML re-emitted verbatim).
• Documented in documentation/TREATMENT-PROCEDURE.md and CHANGELOG.md.
• Non-breaking; consumers ignore unknown fields.

hds-lib-js

• HDSModelStreams#isContext(streamId): boolean helper. Returns true iff the stream definition has role: 'context'. Unknown streamIds return false (no throw).
• 4 new tests in tests/contextResolution.test.js ([CTXR-P/Q/R/S]) loading the real data-model/dist/pack.json.
• No change to runtime D3 walk-up resolution.

Out of scope (Phase B, future)

• hds-forms-js — render context streamId as metadata (tag / header qualifier) rather than as an independent input bucket; suppress "add event under this stream" affordance.
• hds-webapp settings tree — muted / distinct icon for context streams.
• doctor-dashboard patient view — elide context streams from primary navigation, surface as tags in event-detail views.

Phase B lands when triggered by a webapp design pass or a user-reported confusion report.

Open / resolved questions

• ✅ Field name — chose role (not streamType / kind / purpose). Generalizable if a third stream role appears later.
• ✅ Implicit default — absence of role means "data" (the regular case). No declaration required on normal streams.
• ✅ Schema validation — src/streams.js does not run Ajv on stream defs; just YAML-parses and re-emits. New field flows through naturally. No schema work needed.

Plan reference

hds/_macro/_plans/53-handle-stream-context-atwork/PLAN.md (HDS workspace plan tree).