Plan 46 Slice 4: HDSItemDef.matchesEvent + ItemCustomization.context

Two small additions consumed by hds-forms-js Slice 4:

- HDSItemDef.matchesEvent(event) — D3-aware match returning true when an
  event resolves to this itemDef via forEvent (covers both direct
  (streamId, eventType) match and the closest-ancestor walk-up).
  Falls back to plain (streamId-in-streamIds, type-equals-eventType) if
  the model handle isn't available.

- ItemCustomization.context?: string — per-item context streamId on
  CollectorRequest sections. Lets a section emit events placed at a
  descendant streamId of the itemDef's canonical home (e.g. treatment
  itemDef → events at treatment-fertility), threaded through to
  eventTemplate({ context }) at submit time.

4 new [CTXR] tests; 484 total lib tests passing (the two pre-existing
[MODSA]/[MODSB] datasource failures relate to demo.datasafe.dev migration
— see _plans/TODO-ASAP.md).

Tracked: healthdatasafe/data-model#2.

Author: perki

tests/contextResolution.test.js

@@ -116,4 +116,37 @@ describe('[CTXR] Context-via-substream (Plan 46 D3)', () => {
       assert.equal(itemDef.key, 'treatment-basic');
     });
   });
+
+  describe('matchesEvent (D3-aware event matching)', () => {
+    it('[CTXR-L] direct (streamId, eventType) match returns true', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      assert.equal(itemDef.matchesEvent({
+        type: 'treatment/basic',
+        streamIds: ['treatment']
+      }), true);
+    });
+
+    it('[CTXR-M] descendant context resolves via walk-up returns true', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-coded');
+      assert.equal(itemDef.matchesEvent({
+        type: 'treatment/coded-v1',
+        streamIds: ['treatment-fertility']
+      }), true);
+    });
+
+    it('[CTXR-N] cross-tree mismatch returns false', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      assert.equal(itemDef.matchesEvent({
+        type: 'procedure/basic',
+        streamIds: ['procedure-fertility']
+      }), false);
+    });
+
+    it('[CTXR-O] missing streamIds or type returns false', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      assert.equal(itemDef.matchesEvent({}), false);
+      assert.equal(itemDef.matchesEvent({ type: 'treatment/basic' }), false);
+      assert.equal(itemDef.matchesEvent({ streamIds: ['treatment'] }), false);
+    });
+  });
 });

ts/HDSModel/HDSItemDef.ts

@@ -109,4 +109,25 @@ export class HDSItemDef {
       throw new Error(`Context streamId "${candidate}" is not a descendant of itemDef "${this.#key}" streamId "${ancestor}"`);
     }
   }
+
+  /**
+   * D3-aware event-matching. Returns true if the given event resolves to
+   * this itemDef via `model.itemsDefs.forEvent(event)` — covering both the
+   * direct (streamId, eventType) match and the closest-ancestor walk-up.
+   *
+   * Useful in form-engine code that needs to check whether an event belongs
+   * to a particular itemDef without re-implementing the resolution rule.
+   * Falls back to plain `(streamId in event.streamIds, type === eventType)`
+   * if the model handle isn't available.
+   */
+  matchesEvent (event: { type?: string; streamIds?: string[] }): boolean {
+    if (!event || event.type == null || !Array.isArray(event.streamIds)) return false;
+    if (this.#model) {
+      const resolved = this.#model.itemsDefs.forEvent(event, false);
+      return resolved !== null && resolved.key === this.#key;
+    }
+    // Fallback: direct match against this itemDef's streamId + eventType.
+    if (!this.eventTypes.includes(event.type)) return false;
+    return event.streamIds.includes(this.#data.streamId);
+  }
 }

ts/appTemplates/itemLabels.ts

@@ -33,6 +33,14 @@ export interface ItemCustomization {
   repeatable?: string;
   reminder?: Record<string, unknown>;
   labels?: ItemLabels;
+  /**
+   * Plan 46 (D3) — optional context streamId for events created from this
+   * item in this section. Must be `itemDef.streamId` or a descendant; the
+   * itemDef's `eventTemplate({ context })` enforces the constraint.
+   * Lets a single itemDef registered at e.g. `treatment` produce events
+   * placed at `treatment-fertility`, `treatment-oncology`, … per section.
+   */
+  context?: string;
   [key: string]: unknown;
 }