feat: HDSModelOverload — apps can extend the data-model at init time

Adds an optional overload payload to HDSModel.load() / initHDSModel() that
deep-merges into modelData before deepFreeze. Apps can add new itemDefs,
streams, eventTypes, settings, datasources, appStreams, and refine
translations or default repeatable values without forking data-model.

Forbidden mutations (parentId of an existing stream, schema of an existing
eventType, type/streamId/eventType of an existing item, etc.) throw
HDSLibError listing every violation.

extractOverloadAsDefinitions() converts an overload back into a
{filepath: content} map matching data-model/data-model/definitions/ layout
so apps can dump their overload to disk and open a PR upstream.
Browser-safe, no fs, no deps.

35 new tests, all passing. Bump 0.5.0 -> 0.6.0. Plan 34 done.

Author: perki

AppTemplates.md

@@ -141,4 +141,60 @@ Accept current request
 Revoke current request
 
 #### collectorClient.refuse()
-Refuse current request
+Refuse current request
+
+## Overloading the data model
+
+Apps can extend the shared HDS data-model at init time without forking `data-model`. Pass an `HDSModelOverload` to `initHDSModel()`:
+
+```js
+import { initHDSModel, extractOverloadAsDefinitions } from 'hds-lib';
+
+const overload = {
+  // Add brand new items
+  items: {
+    'mood-happy': {
+      version: 'v1',
+      label: { en: 'Happy', fr: 'Heureux' },
+      description: { en: 'Feeling happy' },
+      streamId: 'mood-happy',
+      eventType: 'activity/plain',
+      type: 'checkbox',
+      repeatable: 'unlimited'
+    },
+    // Refine an existing item: add a translation, override repeatable
+    'body-weight': {
+      label: { fr: 'Poids' },
+      repeatable: 'P1D'
+    }
+  },
+  // Add new streams (must hang under an existing parent — or be a new root)
+  streams: [
+    { id: 'mood', name: 'Mood', parentId: null, children: [
+      { id: 'mood-happy', name: 'Happy' }
+    ]}
+  ],
+  // App-specific settings, eventTypes, datasources, appStreams also supported
+  settings: {
+    fontSize: { eventType: 'settings/font-size', type: 'number', default: 14 }
+  }
+};
+
+await initHDSModel({ overload });
+```
+
+The overload is **validated** before merging — attempting to change the `parentId` of an existing stream, the `type`/schema of an existing eventType, or the `type`/`streamId`/`eventType` of an existing item throws `HDSLibError` listing every violation.
+
+To later contribute your overload upstream, dump it to `data-model/data-model/definitions/`-shaped files:
+
+```js
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+const files = extractOverloadAsDefinitions(overload);
+for (const [path, content] of Object.entries(files)) {
+  mkdirSync(dirname(`./out/${path}`), { recursive: true });
+  writeFileSync(`./out/${path}`, content);
+}
+```
+
+Note: runtime overload validation only enforces the policy table (no AJV schema). For full schema validation, run `data-model/data-model/src/schemas/items.js` AJV against your overload at build time.

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### Added
+- `HDSModelOverload` — apps can extend the shared HDS data-model at init time with their own itemDefs, streams, eventTypes, settings, datasources, or appStreams, plus refine translations and default `repeatable` values.
+  - `HDSModel.load(url, overload?)` — merges the overload (after policy validation) before freezing.
+  - `initHDSModel({ overload })` — same hook on the singleton init.
+  - `extractOverloadAsDefinitions(overload)` — converts an overload back into a `{ filepath: content }` map matching the layout under `data-model/data-model/definitions/`, so apps can dump their overload to disk and open a PR upstream. Browser-safe (no `fs`).
+  - Forbidden mutations (changing `parentId` of an existing stream, `type`/schema of an existing eventType, `type`/`streamId`/`eventType` of an existing item, etc.) throw `HDSLibError` listing every violation.
+
 ## [0.5.0] - 2026-04-02
 
 ### Added

package.json

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