feat(plan-59 Phase 5a/5b): FormSpec helpers + Contact.hdsFormSpec passthrough

New module ts/cmc/formSpec.ts (FormSpec brief Candidate C — Q-F1..F5 locks):

- FormSpec interface: title, description, consent, permissions, sections,
  features, customFields, existingStreamRefs, appCustomData.
- saveFormSpec / loadFormSpec — doctor-side canonical template event
  (hds:form-spec-v1) on the :_cmc:apps:hds-collector:<id> scope stream.
- stampFormSpecOnTriggerEvent — doctor-side post-createInvite snapshot
  patch onto the consent/request-cmc trigger event (Q-F2 + Q-F1 locks:
  read-merge-write since events.update replaces content wholesale).
- mirrorFormSpecOnAcceptEvent — patient-side post-acceptInvite mirror
  onto own consent/accept-cmc event so the snapshot survives the
  capability consumption (the doctor's trigger event is unreachable
  from the patient post-accept).
- readOfferWithFormSpec — patient-side pre-accept full-content offer
  read (the SDK's cmc.readOffer filters out HDS-extension fields).
- deriveCmcPermissions — chat-only handling. Injects :hds:noop placeholder
  when FormSpec.permissions is empty (Q-F4 lock).
- provisionHdsNoop — patient-side stream provisioning (Q-F3: patient-only).
- isChatOnlyFormSpec — doctor-side detection helper.

Contact.ts:
- CmcAcceptedRelationship.hdsFormSpec: FormSpec | null — consumer fetches
  raw accept events and surfaces content.hdsFormSpec here.
- CmcRelationship.hdsFormSpec: FormSpec | null — aggregator pass-through.
- Contact.cmcFormSpecs: aggregated specs across relationships.
- Contact.cmcFormSections: aggregated AppTemplateSection[] for the
  Tasks-page recurring-task loop (consumer-compatible with legacy
  CollectorSectionInterface).

Tests: 12 new specs across [CFSC]/[CFSD]/[CFSI]/[CTFS] — constants, derive,
chat-only detection, hdsFormSpec pass-through, aggregator section merge.
501 → 513/513 tests pass; tsc clean.

Index export: cmcFormSpec module + FormSpec type.

Author: perki

tests/cmcFormSpec.test.js

@@ -0,0 +1,171 @@
+import { assert } from './test-utils/deps-node.js';
+import * as cmcFormSpec from '../ts/cmc/formSpec.ts';
+import { Contact } from '../ts/appTemplates/Contact.ts';
+
+/**
+ * Unit tests for the Plan 59 Phase 5a FormSpec helpers + the
+ * `hdsFormSpec` pass-through on Contact.aggregateCmc.
+ *
+ * I/O paths (saveFormSpec / loadFormSpec / mirror) are integration-tested
+ * against a live api-server in the Phase 6 demo iteration loop.
+ */
+
+describe('[CFSP] cmcFormSpec helpers', function () {
+  function basicSpec (overrides = {}) {
+    return {
+      version: 1,
+      title: { en: 'Hello World' },
+      description: { en: 'desc' },
+      consent: { en: 'I consent' },
+      permissions: [{ streamId: 'health', level: 'read' }],
+      sections: [{ key: 'sleep-section', type: 'recurring', name: { en: 'Sleep' }, itemKeys: ['sleep-duration'] }],
+      ...overrides
+    };
+  }
+
+  describe('[CFSC] constants', function () {
+    it('[CFS01] FORM_SPEC_EVENT_TYPE matches the locked Q-F5 name', () => {
+      assert.equal(cmcFormSpec.FORM_SPEC_EVENT_TYPE, 'hds:form-spec-v1');
+    });
+
+    it('[CFS02] HDS_NOOP_STREAM_ID + permission match the brief', () => {
+      assert.equal(cmcFormSpec.HDS_NOOP_STREAM_ID, ':hds:noop');
+      assert.deepEqual(cmcFormSpec.HDS_NOOP_PERMISSION, { streamId: ':hds:noop', level: 'read' });
+    });
+  });
+
+  describe('[CFSD] deriveCmcPermissions', function () {
+    it('[CFS10] returns the FormSpec permissions when non-empty', () => {
+      const spec = basicSpec();
+      const out = cmcFormSpec.deriveCmcPermissions(spec);
+      assert.deepEqual(out, [{ streamId: 'health', level: 'read' }]);
+    });
+
+    it('[CFS11] injects :hds:noop placeholder when permissions empty', () => {
+      const spec = basicSpec({ permissions: [] });
+      const out = cmcFormSpec.deriveCmcPermissions(spec);
+      assert.equal(out.length, 1);
+      assert.equal(out[0].streamId, ':hds:noop');
+      assert.equal(out[0].level, 'read');
+    });
+
+    it('[CFS12] filters out malformed permission entries before deciding empty', () => {
+      const spec = basicSpec({ permissions: [{ streamId: '', level: 'read' }, null, { streamId: 'x' /* no level */ }] });
+      const out = cmcFormSpec.deriveCmcPermissions(spec);
+      // All filtered → placeholder injected
+      assert.equal(out.length, 1);
+      assert.equal(out[0].streamId, ':hds:noop');
+    });
+  });
+
+  describe('[CFSI] isChatOnlyFormSpec', function () {
+    it('[CFS20] true on empty / placeholder-only specs', () => {
+      assert.equal(cmcFormSpec.isChatOnlyFormSpec(basicSpec({ permissions: [] })), true);
+    });
+    it('[CFS21] false when real permissions present', () => {
+      assert.equal(cmcFormSpec.isChatOnlyFormSpec(basicSpec()), false);
+    });
+    it('[CFS22] false for null / undefined input', () => {
+      assert.equal(cmcFormSpec.isChatOnlyFormSpec(null), false);
+      assert.equal(cmcFormSpec.isChatOnlyFormSpec(undefined), false);
+    });
+  });
+});
+
+describe('[CTFS] Contact.aggregateCmc hdsFormSpec pass-through', function () {
+  const SCOPE = ':_cmc:apps:hds-patient';
+
+  function counterpartyAccess (overrides = {}) {
+    const cp = {
+      username: 'drandy',
+      host: 'demo.datasafe.dev',
+      apiEndpoint: 'https://abctoken@drandy.demo.datasafe.dev/',
+      remoteChatStreamId: 'r1',
+      remoteCollectorStreamId: 'c1'
+    };
+    return {
+      id: overrides.id || 'acc-1',
+      permissions: [{ streamId: 'health', level: 'read' }],
+      clientData: {
+        cmc: {
+          role: 'counterparty',
+          appCode: 'hds-collector',
+          features: { chat: true, systemMessaging: true },
+          counterparty: cp
+        }
+      },
+      ...overrides
+    };
+  }
+
+  function acceptEvent (overrides = {}) {
+    return {
+      acceptEventId: overrides.acceptEventId || 'evt-1',
+      counterparty: { username: 'drandy', host: 'demo.datasafe.dev' },
+      appCode: 'hds-collector',
+      scopeStreamId: SCOPE,
+      acceptedAt: 1716000000,
+      features: { chat: true, systemMessaging: true },
+      ...overrides
+    };
+  }
+
+  it('[CTFS1] surfaces hdsFormSpec from the matching accept event', () => {
+    const spec = {
+      version: 1,
+      title: { en: 'Hello World' },
+      description: { en: '' },
+      permissions: [{ streamId: 'health', level: 'read' }],
+      sections: []
+    };
+    const out = Contact.aggregateCmc(
+      [counterpartyAccess()],
+      [acceptEvent({ hdsFormSpec: spec })],
+      SCOPE
+    );
+    assert.equal(out.length, 1);
+    assert.equal(out[0].cmcRelationships[0].hdsFormSpec, spec);
+  });
+
+  it('[CTFS2] hdsFormSpec defaults to null when accept event has none', () => {
+    const out = Contact.aggregateCmc(
+      [counterpartyAccess()],
+      [acceptEvent()],
+      SCOPE
+    );
+    assert.equal(out[0].cmcRelationships[0].hdsFormSpec, null);
+  });
+
+  it('[CTFS3] cmcFormSpecs getter returns specs from all chat-enabled relationships', () => {
+    const spec = { version: 1, title: { en: 'A' }, description: { en: '' }, permissions: [], sections: [{ key: 's', type: 'recurring', name: { en: 'S' }, itemKeys: [] }] };
+    const out = Contact.aggregateCmc(
+      [counterpartyAccess()],
+      [acceptEvent({ hdsFormSpec: spec })],
+      SCOPE
+    );
+    assert.deepEqual(out[0].cmcFormSpecs, [spec]);
+  });
+
+  it('[CTFS4] cmcFormSections aggregates sections across relationships', () => {
+    const spec1 = { version: 1, title: { en: 'A' }, description: { en: '' }, permissions: [], sections: [{ key: 's1', type: 'recurring', name: { en: 'S1' }, itemKeys: ['a'] }] };
+    const spec2 = { version: 1, title: { en: 'B' }, description: { en: '' }, permissions: [], sections: [{ key: 's2', type: 'recurring', name: { en: 'S2' }, itemKeys: ['b'] }] };
+    const a1 = counterpartyAccess({ id: 'a1' });
+    const a2 = counterpartyAccess({ id: 'a2' });
+    const out = Contact.aggregateCmc(
+      [a1, a2],
+      [
+        acceptEvent({ acceptEventId: 'e1', hdsFormSpec: spec1 }),
+        acceptEvent({ acceptEventId: 'e2', hdsFormSpec: spec2 })
+      ],
+      SCOPE
+    );
+    // Both relationships share the same counterparty → one Contact, two relationships.
+    // Both accept events match the same (counterparty, appCode) pair so both
+    // relationships get the FIRST matching spec. That's the documented
+    // behaviour — `matchingAccept` is `accepts.find(...)` (first match).
+    assert.equal(out.length, 1);
+    assert.equal(out[0].cmcRelationships.length, 2);
+    assert.equal(out[0].cmcFormSections.length, 2);
+    assert.deepEqual(out[0].cmcFormSections.map(s => s.key), ['s1', 's1']);
+  });
+});

ts/appTemplates/Contact.ts

@@ -5,6 +5,7 @@ import type { Collector } from './Collector.ts';
 import { HDSModelAppStreams } from '../HDSModel/HDSModel-AppStreams.ts';
 import { getStreamIdAndChildrenIds } from '../toolkit/StreamsTools.ts';
 import { pryv, cmc } from '../patchedPryv.ts';
+import type { FormSpec } from '../cmc/formSpec.ts';
 
 // ---- Plan 59 Phase 5a — CMC-shaped Contact types ---- //
 
@@ -40,6 +41,13 @@ export interface CmcCounterpartyAccess {
  * Patient-side accept-event record — what `cmc.listAcceptedRelationships`
  * returns. Used to enrich the access-derived relationship with
  * `acceptedAt` + reconcile against ghost records.
+ *
+ * `hdsFormSpec` is an HDS-extension field, only present when the patient
+ * mirrors the FormSpec snapshot onto their own accept event content
+ * post-accept (see `cmcFormSpec.mirrorFormSpecOnAcceptEvent`).
+ * Consumers fetching accept events directly (raw `events.get`) should
+ * pass `content.hdsFormSpec` through to this field; the SDK's
+ * `cmc.listAcceptedRelationships` does not return it.
  */
 export interface CmcAcceptedRelationship {
   acceptEventId: string;
@@ -50,6 +58,7 @@ export interface CmcAcceptedRelationship {
   features?: { chat?: boolean; systemMessaging?: boolean; system?: boolean };
   backChannelAccessId?: string | null;
   dataGrantAccessId?: string | null;
+  hdsFormSpec?: FormSpec | null;
 }
 
 /**
@@ -82,6 +91,8 @@ export interface CmcRelationship {
   grantedPermissions: Permission[];
   /** Accept timestamp — null if no matching accept event */
   acceptedAt: number | null;
+  /** FormSpec snapshot mirrored onto the accept event content. Null until the resolver lands (FormSpec brief step 5). */
+  hdsFormSpec: FormSpec | null;
 }
 
 /**
@@ -479,6 +490,39 @@ export class Contact {
       }));
   }
 
+  /**
+   * Resolved FormSpec snapshots across all active CMC relationships.
+   * Skips relationships whose accept event hasn't been mirrored yet
+   * (hdsFormSpec === null). One entry per relationship that has a spec.
+   */
+  get cmcFormSpecs (): FormSpec[] {
+    const result: FormSpec[] = [];
+    for (const rel of this.cmcRelationships) {
+      if (rel.hdsFormSpec) result.push(rel.hdsFormSpec);
+    }
+    return result;
+  }
+
+  /**
+   * Aggregated form sections across all active CMC relationships (Tasks
+   * page recurring-task loop reads this). Pulled from each relationship's
+   * resolved FormSpec; empty if no FormSpecs are mirrored yet.
+   */
+  get cmcFormSections (): import('./interfaces.ts').CollectorSectionInterface[] {
+    const sections: import('./interfaces.ts').CollectorSectionInterface[] = [];
+    for (const rel of this.cmcRelationships) {
+      const spec = rel.hdsFormSpec;
+      if (!spec || !Array.isArray(spec.sections)) continue;
+      // FormSpec sections are AppTemplateSection — cast to the legacy
+      // CollectorSectionInterface for consumer compatibility (same shape
+      // up to a couple of optional fields).
+      for (const s of spec.sections) {
+        sections.push(s as unknown as import('./interfaces.ts').CollectorSectionInterface);
+      }
+    }
+    return sections;
+  }
+
   /** Aggregated granted permissions across all active CMC relationships (deduped by streamId:level) */
   get cmcAllPermissions (): Permission[] {
     const seen = new Set<string>();
@@ -588,7 +632,8 @@ export class Contact {
         appCode,
         features,
         grantedPermissions: access.permissions ?? [],
-        acceptedAt: matchingAccept?.acceptedAt ?? null
+        acceptedAt: matchingAccept?.acceptedAt ?? null,
+        hdsFormSpec: matchingAccept?.hdsFormSpec ?? null
       };
       contact.cmcRelationships.push(rel);
       // Also populate the legacy accessObjects slot so existing event-filtering