Plan 46 Slice 1: context-via-substream resolution + loadFromObject

perki · perki · commit eac5e0beac9e · 2026-04-30T13:33:22.000+02:00
forEvent() now walks parents from streamIds[0] when no direct match is found, returning the closest ancestor's matching itemDef. Direct match across all streamIds is still tried first so legacy multi-streamId events (e.g. bridge-athenahealth) keep resolving with no regression. eventTemplate({ context }) lets a caller emit events placed at descendant streamIds (treatment-fertility, procedure-fertility, …) while keeping the itemDef registered once at the parent (treatment, procedure). Validates the context is in the itemDef's subtree. HDSModel.loadFromObject(data, overload?) extracted from load() — useful for tests and embedded apps; Node's fetch doesn't support file:// URLs so the new contextResolution tests load the locally-built data-model pack.json synchronously via fs and inject it. 11 new [CTXR] tests, all 480 lib tests passing. Tracked: healthdatasafe/data-model#2.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-04-30
+
+### Added (plan 46 — context-via-substream resolution + new public API)
+- **`HDSModelItemsDefs.forEvent()`** — when no direct `(streamId, eventType)` match is found across `event.streamIds`, falls back to walking parents from `event.streamIds[0]` looking for a registered itemDef with the matching eventType. Closest ancestor wins. Lets a single itemDef registered at e.g. `treatment` resolve events placed at `treatment-fertility`, `treatment-oncology`, … without per-domain item definitions. Reuses the existing `streams.getParentsIds` chain helper consumed by `HDSModelAuthorizations`.
+- **`HDSItemDef.eventTemplate({ context })`** — optional `context` streamId per Plan 46 §2.1 (D3). Validates context is `itemDef.streamId` or a descendant; emits length-1 `streamIds: [context ?? streamId]`. Throws on context outside the itemDef's subtree.
+- **`HDSItemDef` constructor takes optional `model: HDSModel`** — used by `eventTemplate` to validate descendant streamIds via `model.streams.getParentsIds`. Backward-compatible: callers that build `HDSItemDef` directly without the model still work; they just can't use the `context` option.
+- **`HDSModel.loadFromObject(data, overload?)`** — loads model from an in-memory object, skipping `fetch`. Useful for tests, embedded apps, or environments where `fetch` can't reach the model URL (e.g. Node's `fetch` does not yet implement `file://`). `load()` is reimplemented in terms of `loadFromObject`.
+
+### Notes
+- D3's walk-up is the third application of the same closest-ancestor algorithm in this lib: Plan 45's `resolveStream.ts` (account-level `clientData` lookup) and `HDSModelAuthorizations` (parent-covers-child de-dup) are the existing precedents. D3 applies the algorithm at the data-model itemDef layer.
+- 11 new `[CTXR]` tests in `tests/contextResolution.test.js` exercising the resolution + creation paths plus the legacy multi-streamId case.
+
 ## [0.9.1] - 2026-04-28
 
 ### Fixed — `CollectorRequestSection` round-trip for `customFieldKeys[]`
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hds-lib",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Health Data Safe - Library",
   "type": "module",
   "engines": {
diff --git a/tests/contextResolution.test.js b/tests/contextResolution.test.js
@@ -0,0 +1,119 @@
+import { assert } from './test-utils/deps-node.js';
+import { HDSModel } from '../ts/HDSModel/HDSModel.ts';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Plan 46 §2.1 — Context-via-substream resolution (D3).
+ *
+ * Validates the data-model + hds-lib-js implementation end-to-end by loading
+ * the locally-built data-model pack.json (so it includes the new treatment-* /
+ * procedure-* items registered at parent streams with -fertility context
+ * children). Uses loadFromObject to bypass fetch, since Node's fetch does
+ * not support file:// URLs.
+ */
+const localPackPath = path.resolve(
+  process.cwd(),
+  '../../data-model/data-model/dist/pack.json'
+);
+
+describe('[CTXR] Context-via-substream (Plan 46 D3)', () => {
+  let model;
+  before(() => {
+    const packJson = JSON.parse(fs.readFileSync(localPackPath, 'utf8'));
+    model = new HDSModel('local-test');
+    model.loadFromObject(packJson);
+  });
+
+  describe('forEvent — walk-up resolution', () => {
+    it('[CTXR-A] direct (streamId, eventType) match still works', () => {
+      const itemDef = model.itemsDefs.forEvent({
+        type: 'treatment/basic',
+        streamIds: ['treatment']
+      });
+      assert.equal(itemDef.key, 'treatment-basic');
+    });
+
+    it('[CTXR-B] descendant streamId resolves via parent walk-up', () => {
+      const itemDef = model.itemsDefs.forEvent({
+        type: 'treatment/basic',
+        streamIds: ['treatment-fertility']
+      });
+      assert.equal(itemDef.key, 'treatment-basic');
+    });
+
+    it('[CTXR-C] coded variant resolves via walk-up from procedure-fertility', () => {
+      const itemDef = model.itemsDefs.forEvent({
+        type: 'procedure/coded-v1',
+        streamIds: ['procedure-fertility']
+      });
+      assert.equal(itemDef.key, 'procedure-coded');
+    });
+
+    it('[CTXR-D] returns null when type+stream cross trees with no match', () => {
+      const itemDef = model.itemsDefs.forEvent(
+        { type: 'procedure/coded-v1', streamIds: ['treatment-fertility'] },
+        false
+      );
+      assert.equal(itemDef, null);
+    });
+
+    it('[CTXR-E] throws by default when nothing resolves', () => {
+      assert.throws(
+        () => model.itemsDefs.forEvent({ type: 'no-such/type', streamIds: ['treatment'] }),
+        /Cannot find definition/
+      );
+    });
+  });
+
+  describe('eventTemplate({ context })', () => {
+    it('[CTXR-F] no context falls back to itemDef streamId', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      const tmpl = itemDef.eventTemplate();
+      assert.deepEqual(tmpl.streamIds, ['treatment']);
+      assert.equal(tmpl.type, 'treatment/basic');
+    });
+
+    it('[CTXR-G] context equal to itemDef streamId emits same value', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      const tmpl = itemDef.eventTemplate({ context: 'treatment' });
+      assert.deepEqual(tmpl.streamIds, ['treatment']);
+    });
+
+    it('[CTXR-H] descendant context produces length-1 streamIds with that context', () => {
+      const itemDef = model.itemsDefs.forKey('procedure-basic');
+      const tmpl = itemDef.eventTemplate({ context: 'procedure-fertility' });
+      assert.deepEqual(tmpl.streamIds, ['procedure-fertility']);
+      assert.equal(tmpl.type, 'procedure/basic');
+    });
+
+    it('[CTXR-I] context outside subtree throws', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      assert.throws(
+        () => itemDef.eventTemplate({ context: 'procedure-fertility' }),
+        /not a descendant/
+      );
+    });
+
+    it('[CTXR-J] unknown context streamId throws', () => {
+      const itemDef = model.itemsDefs.forKey('treatment-basic');
+      assert.throws(
+        () => itemDef.eventTemplate({ context: 'no-such-stream' }),
+        /not a descendant/
+      );
+    });
+  });
+
+  describe('legacy multi-streamId resolution still works (no regression)', () => {
+    it('[CTXR-K] event with multiple streamIds resolves via direct match', () => {
+      // bridge-athenahealth pattern: streamIds carry both the canonical home
+      // and a secondary index stream. Resolution should succeed via direct
+      // match on either streamId, before walk-up triggers.
+      const itemDef = model.itemsDefs.forEvent({
+        type: 'treatment/basic',
+        streamIds: ['treatment-fertility', 'treatment']
+      });
+      assert.equal(itemDef.key, 'treatment-basic');
+    });
+  });
+});
diff --git a/ts/HDSModel/HDSItemDef.ts b/ts/HDSModel/HDSItemDef.ts
@@ -1,4 +1,5 @@
 import { localizeText } from '../localizeText.ts';
+import type { HDSModel } from './HDSModel.ts';
 
 export interface ReminderConfig {
   cooldown?: string;
@@ -11,10 +12,18 @@ export interface ReminderConfig {
 export class HDSItemDef {
   #data: any;
   #key: string;
+  /**
+   * Optional model handle, used to validate descendant streamIds in
+   * `eventTemplate({ context })`. Constructed by HDSModelItemsDefs which has
+   * the model handle available; older callers that build HDSItemDef directly
+   * still work — they just can't use the `context` option.
+   */
+  #model: HDSModel | null;
 
-  constructor (key: string, definitionData: any) {
+  constructor (key: string, definitionData: any, model: HDSModel | null = null) {
     this.#key = key;
     this.#data = definitionData;
+    this.#model = model;
   }
 
   get eventTypes (): string[] {
@@ -60,15 +69,44 @@ export class HDSItemDef {
 
   /**
    * a template event with eventType and streamIds
+   *
+   * @param opts.context — optional context streamId per Plan 46 §2.1 (D3).
+   *   Must equal `this.streamId` or be a descendant. Lets a single itemDef
+   *   registered at e.g. `treatment` produce events placed at `treatment-fertility`,
+   *   `treatment-oncology`, etc., without per-domain item definitions.
+   *   When omitted, falls back to the itemDef's canonical streamId.
+   *   Throws if the context isn't in the itemDef's subtree.
+   *
    * // TODO handle variations
    */
-  eventTemplate (): {
+  eventTemplate (opts: { context?: string } = {}): {
     streamIds: [string];
     type: string;
   } {
+    let chosenStreamId = this.#data.streamId as string;
+    if (opts.context != null && opts.context !== chosenStreamId) {
+      this.#assertDescendantOf(opts.context, chosenStreamId);
+      chosenStreamId = opts.context;
+    }
     return {
-      streamIds: [this.#data.streamId],
+      streamIds: [chosenStreamId],
       type: this.eventTypes[0]
     };
   }
+
+  /**
+   * Throws if `candidate` is not a descendant of `ancestor` in the model's
+   * stream tree. Requires the model handle (passed at construction).
+   */
+  #assertDescendantOf (candidate: string, ancestor: string): void {
+    if (!this.#model) {
+      throw new Error(`HDSItemDef "${this.#key}" was constructed without a model handle; cannot validate context "${candidate}"`);
+    }
+    // getParentsIds returns ancestors (excluding self). Treat candidate as
+    // valid iff `ancestor` is in its parent chain.
+    const ancestors = this.#model.streams.getParentsIds(candidate, false);
+    if (!ancestors.includes(ancestor)) {
+      throw new Error(`Context streamId "${candidate}" is not a descendant of itemDef "${this.#key}" streamId "${ancestor}"`);
+    }
+  }
 }
diff --git a/ts/HDSModel/HDSModel-ItemsDefs.ts b/ts/HDSModel/HDSModel-ItemsDefs.ts
@@ -61,12 +61,22 @@ export class HDSModelItemsDefs {
       if (throwErrorIfNotFound) throw new Error('Cannot find item definition with key: ' + key);
       return null;
     }
-    this.#itemsDefs[key] = new HDSItemDef(key, defData);
+    this.#itemsDefs[key] = new HDSItemDef(key, defData, this.#model);
     return this.#itemsDefs[key];
   }
 
   /**
    * get a definition for an event
+   *
+   * Resolution rule (Plan 46 §2.1 — context-via-substream / D3):
+   *   1. Try direct match on every entry in event.streamIds (legacy: events
+   *      may carry multiple streamIds, e.g. bridge-athenahealth credentials).
+   *   2. If no direct match, walk parents of streamIds[0] looking for a
+   *      matching itemDef. Closest ancestor wins.
+   *
+   * The walk-up reuses `HDSModelStreams.getParentsIds`, the same helper
+   * Authorizations consumes (HDSModel-Authorizations.ts:86) and the same
+   * algorithm Plan 45's resolveStream.ts uses for clientData lookup.
    */
   forEvent (event: any, throwErrorIfNotFound: boolean = true): HDSItemDef | null {
     const candidates: any[] = [];
@@ -75,6 +85,23 @@ export class HDSModelItemsDefs {
       const candidate = this.#modelDataByStreamIdEventTypes[keyStreamIdEventType];
       if (candidate) candidates.push(candidate);
     }
+    if (candidates.length === 0 && event.streamIds && event.streamIds.length > 0) {
+      const primary = event.streamIds[0];
+      // getParentsIds returns root-first ancestors of `primary` (excludes self).
+      // We need closest-ancestor-wins, so iterate leaf-to-root: walk parents
+      // in reverse, then check `primary` is already covered by the direct-match
+      // pass above — so we only need ancestors here.
+      const ancestorsRootFirst = this.#model.streams.getParentsIds(primary, false);
+      for (let i = ancestorsRootFirst.length - 1; i >= 0; i--) {
+        const ancestorId = ancestorsRootFirst[i];
+        const keyStreamIdEventType = ancestorId + ':' + event.type;
+        const candidate = this.#modelDataByStreamIdEventTypes[keyStreamIdEventType];
+        if (candidate) {
+          candidates.push(candidate);
+          break;
+        }
+      }
+    }
     if (candidates.length === 0) {
       if (throwErrorIfNotFound) throw new Error('Cannot find definition for event: ' + JSON.stringify(event));
       return null;
diff --git a/ts/HDSModel/HDSModel.ts b/ts/HDSModel/HDSModel.ts
@@ -73,11 +73,21 @@ export class HDSModel {
     const response = await fetch(this.#modelUrl);
     const resultText = await response.text();
     const result = JSON.parse(resultText);
+    this.loadFromObject(result, overload);
+  }
+
+  /**
+   * Load model from an in-memory object (skips fetch). Useful when the
+   * pack.json content is already in memory — tests, embedded apps, or
+   * environments where fetch can't reach the model URL (e.g. Node with a
+   * file:// URL, which Node's fetch does not yet implement).
+   */
+  loadFromObject (data: any, overload: HDSModelOverload | null = null): void {
     if (overload) {
-      validateOverload(result, overload);
-      applyOverload(result, overload);
+      validateOverload(data, overload);
+      applyOverload(data, overload);
     }
-    this.#modelData = result;
+    this.#modelData = data;
     // add key to items before freezing;
     for (const [key, item] of Object.entries(this.#modelData.items)) {
       (item as any).key = key;

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "hds-lib",`
`3`		`- "version": "0.9.1",`
	`3`	`+ "version": "0.10.0",`
`4`	`4`	`"description": "Health Data Safe - Library",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"engines": {`