v0.8.0 — system stream MVP + appTemplates existingStreamRefs (plan 45)

CollectorRequest: new top-level existingStreamRefs[] (Plan 45 §2.9 mode-3) for
requesting access on pre-existing streams without provisioning. addExistingStreamRef()
validates input. Type ExistingStreamRef exported.

CollectorClient.accept(): processes existingStreamRefs[] — bootstrap-provisions
app-system / app-system-out / app-system-in streams (idempotent), appends requested
permissions to the granted access, surfaces system-stream wiring on
responseContent.system = { streamOut?, streamIn? }.

CollectorInvite: hasSystem getter, systemSettings, systemPostAlert(), systemPollAcks(),
systemEventInfos(). Posts message/system-alert and reads message/system-ack.

Collector.checkInbox(): also propagates responseEvent.content.system to the
operator's invite content (was only copying chat). Without this the operator's
hasSystem stayed false even when the patient's accept flow surfaced the system
wiring — discovered during the smoke test, end-to-end verified programmatically.

Tests: 8 new in apptemplatesRequest.test.js covering existingStreamRefs validation,
serialization, mixed-mode requests.

Requires data-model ≥ 1.6.0.

Author: perki

AGENTS.md

@@ -97,7 +97,7 @@ Every value/type intended for external consumption is exported from [`ts/index.t
 
 - **`tsc` stale output**: `tsc` may skip re-emitting a `.js` file if it already exists and didn't notice an internal change. After `npm run prepare` / `npm run build:ts`, **verify the relevant file in `js/` actually contains your change** before committing. If not, delete the stale `js/<path>.js` and re-run.
 - **Vite cache in consumer apps**: when you change a public type or export and a consumer app (Vite-based) doesn't pick it up, clear `<consumer>/node_modules/.vite` and restart the dev server.
-- **npm-link traps**: when an HDS app is npm-linked to `hds-lib`, both the app and any nested package (e.g. `hds-forms-js`'s [`src-test-app/`](https://github.com/healthdatasafe/hds-forms-js/tree/main/src-test-app)) must link the **same** `hds-lib` to avoid duplicate singletons (settings, model). If you see "two HDSModels" symptoms (e.g. `getHDSModel()` returning empty), this is the cause. **Run `cd _local && npm run check-links && npm run verify-live-source`** to diagnose. Full methodology: `_macro/_claude-memory/conventions.md § Live cross-repo development — quickstart` + `_plans/49-local-dev-dependency-graph-study/PLAN.md`.
+- **npm-link traps**: when an HDS app is npm-linked to `hds-lib`, both the app and any nested package (e.g. `hds-forms-js`'s [`src-test-app/`](https://github.com/healthdatasafe/hds-forms-js/tree/main/src-test-app)) must link the **same** `hds-lib` to avoid duplicate singletons (settings, model). If you see "two HDSModels" symptoms (e.g. `getHDSModel()` returning empty), this is the cause. **Run `cd _local && npm run check-links && npm run verify-live-source`** to diagnose. Full methodology: `_claude-memory/conventions.md § Live cross-repo development — quickstart` + `_plans/49-local-dev-dependency-graph-done/PLAN.md`.
 - **`exports.import` MUST point at TS source** (`./ts/index.ts` here). Vite resolves the `import` condition in dev mode; pointing at compiled JS causes downstream libs (hds-forms-js, hds-react-timeline) to inline a second copy of `hds-lib` → duplicate-singleton bug. Verify with `cd _local && npm run verify-live-source`.
 - **Initialization order**: in apps that call `initBoiler(name, configDir)` (server side) or `pryv.Browser.AuthController` (client side), do so **before** any `getHDSModel()` / `HDSSettings` lookup.
 

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-04-28
+
+### Added — Plan 45 Phase 3a (system stream MVP slice)
+
+#### `CollectorRequest` (`ts/appTemplates/CollectorRequest.ts`)
+- New top-level field `existingStreamRefs[]` (Plan 45 §2.9 mode-3): request access on pre-existing streams without provisioning. Each ref carries `{ streamId, permissions: ('read'|'manage'|'contribute')[], purpose? }`.
+- New methods: `addExistingStreamRef(ref)` with input validation (rejects non-string streamId, empty permissions, unknown permission levels) and `existingStreamRefs` getter.
+- `content` getter now serializes `existingStreamRefs[]` when non-empty (omitted otherwise — backwards-compatible).
+- New exported type: `ExistingStreamRef`.
+
+#### `CollectorClient` (`ts/appTemplates/CollectorClient.ts`)
+- `accept()` now processes `requestData.existingStreamRefs[]` after the existing chat-stream block:
+  1. **Bootstrap-provision** `app-system` / `app-system-out` / `app-system-in` streams if a ref points at the system pair and the streams don't exist yet. The new streams carry `clientData.hdsSystemFeature` declaring `message/system-alert` (on `out`) and `message/system-ack` (on `in`). Idempotent — `item-already-exists` errors from `streams.create` are tolerated.
+  2. Append the requested permissions to the access being granted.
+  3. Surface system-stream wiring on `responseContent.system = { streamOut?, streamIn? }` when `app-system-*` refs are present.
+
+#### `CollectorInvite` (`ts/appTemplates/CollectorInvite.ts`)
+- New properties: `hasSystem`, `systemSettings` (returns `{ streamOut?, streamIn? }`).
+- New methods (mirroring `chatPost` / `chatEventInfos`):
+  - `systemPostAlert({ level, title, body, ackRequired?, ackId? })` — posts a `message/system-alert` to `streamOut`. Auto-generates a UUID `ackId` when `ackRequired: true` and none supplied.
+  - `systemPollAcks({ ackId?, limit? })` — fetches `message/system-ack` events from `streamIn`, optionally filtered by `ackId`. Returns events sorted ascending by creation time.
+  - `systemEventInfos(event)` — identifies the source of a system event (`'me'`/`'user'`/`'unknown'`).
+
+### Changed — `package.json.exports.import` → TS source (Plan 49)
+- `exports[.].import` switched from `./js/index.js` (compiled JS) to `./ts/index.ts` (TS source). Added wildcard `./js/*` subpath export. `default` still points at compiled JS for non-Vite/CJS consumers.
+- This brings hds-lib in line with `_claude-memory/conventions.md § Package exports: TS source for bundlers` and is the prerequisite for live cross-repo dev (the previous `js/index.js` import path created duplicate-singleton bugs when downstream libs like hds-forms-js re-imported `hds-lib` via `require()`). See `_plans/49-local-dev-dependency-graph-done/PLAN.md` for the full rationale.
+
+### Notes
+- The Plan-45 Phase 3a additions are the **MVP slice** of system-stream support. Full Phase 3 work (custom-fields helpers `resolveStreamCustomField` + `streamCustomFieldToVirtualItem`, the appTemplates loader with Ajv schema, sandbox-prefix enforcement) lands in a follow-up commit.
+- Designed to be consumed by:
+  - **`doctor-dashboard`** Phase 6a — operator UI calling `invite.systemPostAlert(...)` and `invite.systemPollAcks(...)`.
+  - **`hds-webapp`** Phase 7a — patient-side inbox provisioning the `app-system/*` streams at boot (or relying on `CollectorClient`'s bootstrap fallback) and rendering alerts with an Acknowledge button that posts `message/system-ack`.
+- Requires `data-model` ≥ 1.4.0 (the new `message/system-alert` + `message/system-ack` event types).
+- See `_plans/45-custom-fields-appTemplates-paused/spec.md` for the locked design.
+
 ## [0.7.2] - 2026-04-28
 
 ### Added — runtime support for `deprecated: true` itemDefs (Plan 50)
@@ -22,7 +57,7 @@ Contract documented in `data-model/AGENTS.md § "deprecated: true on items"`.
 
 **Why.** Vite resolves the `import` condition in dev mode. With `import` pointing at compiled JS, live edits to `ts/*.ts` weren't reflected in npm-linked consumers without rebuilding hds-lib-js. Pointing `import` at TS source enables true live cross-repo development. This also avoids the duplicate-singleton bug surfaced by Plan 45 (a downstream lib's pre-built bundle inlining a second copy of `hds-lib`'s `HDSModel`). Production builds and CJS consumers are unaffected (still hit `default`).
 
-Brings `hds-lib` in line with `_claude-memory/conventions.md § Package exports: TS source for bundlers`. See `_plans/49-local-dev-dependency-graph-study/PLAN.md` for the full rationale.
+Brings `hds-lib` in line with `_claude-memory/conventions.md § Package exports: TS source for bundlers`. See `_plans/49-local-dev-dependency-graph-done/PLAN.md` for the full rationale.
 
 ## [0.7.0] - 2026-04-27
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hds-lib",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Health Data Safe - Library",
   "type": "module",
   "engines": {

tests/apptemplatesRequest.test.js

@@ -304,4 +304,78 @@ describe('[APRX] appTemplates Requests', function () {
     };
     assert.deepEqual(requestContent, expectedContent);
   });
+
+  describe('[APRES] CollectorRequest existingStreamRefs (Plan 45)', function () {
+    it('[ARES1] should parse existingStreamRefs from content', () => {
+      const request = new CollectorRequest({
+        existingStreamRefs: [
+          { streamId: 'app-system-out', permissions: ['manage'], purpose: 'system-out' },
+          { streamId: 'app-system-in', permissions: ['read'], purpose: 'system-in' }
+        ]
+      });
+      assert.equal(request.existingStreamRefs.length, 2);
+      assert.equal(request.existingStreamRefs[0].streamId, 'app-system-out');
+      assert.deepEqual(request.existingStreamRefs[0].permissions, ['manage']);
+      assert.equal(request.existingStreamRefs[1].streamId, 'app-system-in');
+    });
+
+    it('[ARES2] should serialize existingStreamRefs in content', () => {
+      const request = new CollectorRequest({});
+      request.addExistingStreamRef({ streamId: 'app-system-out', permissions: ['manage'] });
+      assert.ok(request.content.existingStreamRefs);
+      assert.equal(request.content.existingStreamRefs.length, 1);
+      assert.equal(request.content.existingStreamRefs[0].streamId, 'app-system-out');
+    });
+
+    it('[ARES3] should not serialize existingStreamRefs when empty', () => {
+      const request = new CollectorRequest({});
+      assert.equal(request.content.existingStreamRefs, undefined);
+    });
+
+    it('[ARES4] should reject non-string streamId', () => {
+      const request = new CollectorRequest({});
+      try {
+        request.addExistingStreamRef({ streamId: 123, permissions: ['read'] });
+        throw new Error('Should throw error');
+      } catch (e) {
+        assert.match(e.message, /streamId must be a non-empty string/);
+      }
+    });
+
+    it('[ARES5] should reject empty permissions array', () => {
+      const request = new CollectorRequest({});
+      try {
+        request.addExistingStreamRef({ streamId: 'app-system-out', permissions: [] });
+        throw new Error('Should throw error');
+      } catch (e) {
+        assert.match(e.message, /permissions must be a non-empty array/);
+      }
+    });
+
+    it('[ARES6] should reject invalid permission level', () => {
+      const request = new CollectorRequest({});
+      try {
+        request.addExistingStreamRef({ streamId: 'app-system-out', permissions: ['admin'] });
+        throw new Error('Should throw error');
+      } catch (e) {
+        assert.match(e.message, /Invalid permission level "admin"/);
+      }
+    });
+
+    it('[ARES7] should accept all three permission levels', () => {
+      const request = new CollectorRequest({});
+      request.addExistingStreamRef({ streamId: 's1', permissions: ['read'] });
+      request.addExistingStreamRef({ streamId: 's2', permissions: ['manage'] });
+      request.addExistingStreamRef({ streamId: 's3', permissions: ['contribute'] });
+      assert.equal(request.existingStreamRefs.length, 3);
+    });
+
+    it('[ARES8] should round-trip through setContent', () => {
+      const r1 = new CollectorRequest({});
+      r1.addExistingStreamRef({ streamId: 'app-system-out', permissions: ['manage'], purpose: 'system' });
+      const content1 = r1.content;
+      const r2 = new CollectorRequest(content1);
+      assert.deepEqual(r2.existingStreamRefs, r1.existingStreamRefs);
+    });
+  });
 });

ts/appTemplates/Collector.ts

@@ -219,12 +219,14 @@ export class Collector {
           (updateInvite as any).streamIds = [this.streamIdFor(Collector.STREAMID_SUFFIXES.active)];
           updateInvite.content.apiEndpoint = responseEvent.content.apiEndpoint;
           if (responseEvent.content.chat) updateInvite.content.chat = responseEvent.content.chat;
+          if (responseEvent.content.system) updateInvite.content.system = responseEvent.content.system;
           break;
         case 'update-accept':
           // Patient accepted an access update — new apiEndpoint, stays active
           (updateInvite as any).streamIds = [this.streamIdFor(Collector.STREAMID_SUFFIXES.active)];
           updateInvite.content.apiEndpoint = responseEvent.content.apiEndpoint;
           if (responseEvent.content.chat) updateInvite.content.chat = responseEvent.content.chat;
+          if (responseEvent.content.system) updateInvite.content.system = responseEvent.content.system;
           break;
         case 'update-refuse':
           // Patient refused the update — invite stays active with current permissions

ts/appTemplates/CollectorClient.ts

@@ -196,7 +196,7 @@ export class CollectorClient {
    * @param {boolean} forceAndSkipAccessCreation - internal temporary option,
    */
   async accept (forceAndSkipAccessCreation = false) {
-    const responseContent: { apiEndpoint?: string, chat?: any } = {};
+    const responseContent: { apiEndpoint?: string, chat?: any, system?: any } = {};
     if (this.accessData && this.accessData.deleted == null && this.status !== 'Active') {
       forceAndSkipAccessCreation = true;
       logger.error('CollectorClient.accept TODO fix accept when access valid');
@@ -240,6 +240,72 @@ export class CollectorClient {
         // ---------- end chat ---------- //
       }
 
+      // ------------- existingStreamRefs (Plan 45 mode-3) ------------------------ //
+      const existingStreamRefs: Array<{ streamId: string, permissions: string[], purpose?: string }> =
+        this.requestData.existingStreamRefs || [];
+      if (existingStreamRefs.length > 0) {
+        // 1. Bootstrap-provision `app-system-*` streams if any ref points there and they don't yet exist.
+        //    (Defensive — `hds-webapp` provisions them at account setup; this safety net handles users
+        //    reaching HDS via an invite without ever opening hds-webapp first.)
+        const needsAppSystem = existingStreamRefs.some((r) =>
+          r.streamId === 'app-system-out' || r.streamId === 'app-system-in'
+        );
+        if (needsAppSystem) {
+          const appSystemBootstrap = [
+            { method: 'streams.create', params: { name: 'System', id: 'app-system' } },
+            {
+              method: 'streams.create',
+              params: {
+                name: 'System out',
+                id: 'app-system-out',
+                parentId: 'app-system',
+                clientData: {
+                  hdsSystemFeature: {
+                    'message/system-alert': { version: 'v1', levels: ['info', 'warning', 'critical'] }
+                  }
+                }
+              }
+            },
+            {
+              method: 'streams.create',
+              params: {
+                name: 'System in',
+                id: 'app-system-in',
+                parentId: 'app-system',
+                clientData: {
+                  hdsSystemFeature: {
+                    'message/system-ack': { version: 'v1' }
+                  }
+                }
+              }
+            }
+          ];
+          const bootstrapResults = await this.app.connection.api(appSystemBootstrap);
+          bootstrapResults.forEach((r) => {
+            if (r.stream?.id || r.error?.id === 'item-already-exists') return;
+            throw new HDSLibError('Failed bootstrapping app-system streams', bootstrapResults);
+          });
+        }
+
+        // 2. Append the requested permissions to the access being granted.
+        for (const ref of existingStreamRefs) {
+          for (const level of ref.permissions) {
+            cleanedPermissions.push({ streamId: ref.streamId, level });
+          }
+        }
+
+        // 3. Surface system-stream wiring on responseContent.system if app-system-* refs are present.
+        const outRef = existingStreamRefs.find((r) => r.streamId === 'app-system-out');
+        const inRef = existingStreamRefs.find((r) => r.streamId === 'app-system-in');
+        if (outRef || inRef) {
+          responseContent.system = {
+            ...(outRef ? { streamOut: 'app-system-out' } : {}),
+            ...(inRef ? { streamIn: 'app-system-in' } : {})
+          };
+        }
+      }
+      // ---------- end existingStreamRefs ---------- //
+
       const accessCreateData = {
         name: this.key,
         type: 'shared',

ts/appTemplates/CollectorInvite.ts

@@ -2,6 +2,21 @@ import { pryv } from '../patchedPryv.ts';
 import { HDSLibError } from '../errors.ts';
 import type { ContactSource } from './interfaces.ts';
 
+/** Generate a v4-ish UUID. Uses crypto.randomUUID() when available, falls back to a manual impl. */
+function newUuid (): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
+  // RFC4122-ish v4 fallback
+  const hex = '0123456789abcdef';
+  let s = '';
+  for (let i = 0; i < 36; i++) {
+    if (i === 8 || i === 13 || i === 18 || i === 23) s += '-';
+    else if (i === 14) s += '4';
+    else if (i === 19) s += hex[(Math.random() * 4 | 0) + 8];
+    else s += hex[Math.random() * 16 | 0];
+  }
+  return s;
+}
+
 /**
  * Collector Invite
  * There is one Collector Invite per Collector => Enduser connection
@@ -75,6 +90,73 @@ export class CollectorInvite {
     return await this.connection.apiOne('events.create', newEvent, 'event');
   }
 
+  // -------------------- system stream (Plan 45) ----------------- //
+  /** Whether this invite has system-stream access (operator → user alerts + user → operator acks). */
+  get hasSystem (): boolean {
+    return this.eventData.content.system != null;
+  }
+
+  /** Stream wiring for the system feature. streamOut is the operator's write target; streamIn is read. */
+  get systemSettings (): { streamOut?: string, streamIn?: string } {
+    return this.eventData.content.system || {};
+  }
+
+  /** Identify the source of a system event. */
+  systemEventInfos (event: pryv.Event): { source: 'me' | 'user' | 'unknown' } {
+    const s = this.systemSettings;
+    if (s.streamOut && event.streamIds.includes(s.streamOut)) return { source: 'me' };
+    if (s.streamIn && event.streamIds.includes(s.streamIn)) return { source: 'user' };
+    return { source: 'unknown' };
+  }
+
+  /**
+   * Post a system alert to the user. Generates ackId if ackRequired and not provided.
+   * Requires `hasSystem === true` and `systemSettings.streamOut` (manage permission).
+   */
+  async systemPostAlert (alert: {
+    level: 'info' | 'warning' | 'critical',
+    title: string,
+    body: string,
+    ackRequired?: boolean,
+    ackId?: string
+  }): Promise<pryv.Event> {
+    const s = this.systemSettings;
+    if (!s.streamOut) throw new HDSLibError('No system streamOut on this invite');
+    const content: any = { level: alert.level, title: alert.title, body: alert.body };
+    if (alert.ackRequired) {
+      content.ackRequired = true;
+      content.ackId = alert.ackId || newUuid();
+    } else if (alert.ackId) {
+      content.ackId = alert.ackId;
+    }
+    const newEvent = {
+      type: 'message/system-alert',
+      streamIds: [s.streamOut],
+      content
+    };
+    return await this.connection.apiOne('events.create', newEvent, 'event');
+  }
+
+  /**
+   * Read system-ack events for this invite, optionally filtered by alert ackId.
+   * Returns events sorted ascending by `created`.
+   */
+  async systemPollAcks (filter: { ackId?: string, limit?: number } = {}): Promise<pryv.Event[]> {
+    const s = this.systemSettings;
+    if (!s.streamIn) throw new HDSLibError('No system streamIn on this invite');
+    const params: any = {
+      streams: [s.streamIn],
+      types: ['message/system-ack'],
+      limit: filter.limit ?? 100,
+      sortAscending: true
+    };
+    const events = await this.connection.apiOne('events.get', params, 'events');
+    if (filter.ackId) {
+      return (events as pryv.Event[]).filter((e: any) => e.content?.ackId === filter.ackId);
+    }
+    return events as pryv.Event[];
+  }
+
   /**
    * Check if connection is valid. (only if active)
    * If result is "forbidden" update and set as revoked