vet-sdk-core-ts 0.4.11 → 0.4.13

package/README.md

@@ -21,7 +21,17 @@ read, update and search for ResearchSubjects filtered by the exact study. It
 never requests deletion of the twin; deletion of selected clinical facts must
 target those concrete resources under an active controller-approved Consent.
 The builder fails closed unless the professional has completed DCR and the
-later controller-approved Consent is `active`.
+later controller-approved Consent is `active`. It emits the canonical purpose
+`HRESCH` and the unescaped scope
+`organization/ResearchSubject.crus?study=ResearchStudy/<id>` so it can be
+passed to the protected professional runtime; the DCR-bound runtime supplies
+the professional actor as `sub`.
+
+`buildVeterinaryResearchStudyActiveConsentBatch` builds the controller's
+separate JSON:API `Consent/_batch`. Every POST is fixed to `active`, `permit`,
+`HRESCH`, one `PractitionerRole`, its ISCO-08 role, and that same exact
+ResearchStudy scope. The API does not accept caller-authored actions, so it
+cannot be broadened to delete.
 
 `buildVeterinaryResearchStudyPartyInvitations` creates exactly one R5
 `Communication` per associated `PractitionerRole`. Each Communication carries
@@ -31,6 +41,19 @@ to the ResearchStudy through `Consent.provision.data.reference` and to
 only create, read, update and search. It contains no delete permission and
 never authorizes SMART access.
 
+`buildVeterinaryResearchStudyGroupCreateEntry` and
+`buildVeterinaryResearchStudyGroupMemberPatchEntries` build the native R5 Group
+POST/PATCH entries for an enumerated professional review team. Every member is
+a registered `PractitionerRole`; the exact twelve Group search claims are
+derived from `vet-data-utils-ts/group`. The ResearchStudy points to the team
+through the reference returned by
+`buildVeterinaryResearchStudyEligibilityGroupReference`, used as
+`ResearchStudy.recruitment.eligibility`.
+`buildVeterinaryResearchStudyEligibilityGroupPatchEntry` links an existing
+study and is wrapped by `buildVeterinaryResearchStudyBatch`; it does not invent
+a mixed-resource gateway batch. Group itself contains no reverse study link
+and grants no authorization, permission or SMART scope.
+
 The complete controller-to-professional contract and a browser-safe snippet
 are in
 [`docs/101-RESEARCH-STUDY-INVITATIONS.md`](docs/101-RESEARCH-STUDY-INVITATIONS.md).
@@ -41,6 +64,8 @@ FHIR references:
 - https://hl7.org/fhir/R5/researchsubject-search.html
 - https://hl7.org/fhir/R5/communication.html
 - https://hl7.org/fhir/R5/consent-definitions.html
+- https://hl7.org/fhir/R5/group.html
+- https://hl7.org/fhir/R5/group-search.html
 
 ## Reusable professional BFF
 

package/dist/research-study.d.ts

@@ -1,14 +1,18 @@
 import { type ResearchStudyAssociatedParty } from 'vet-data-utils-ts/research-study';
+import { type GroupR5ResearchTeam } from 'vet-data-utils-ts/group';
+import { HealthcareConsentPurposes } from 'gdc-common-utils-ts/constants/healthcare';
+import { ResourceTypesFhirR5 } from 'gdc-common-utils-ts/constants/fhir-resource-types';
+import { ClaimConsent, ConsentStatuses } from 'gdc-common-utils-ts/models/consent-rule';
 export declare const VeterinaryResearchStudyPermissionActions: readonly ["create", "read", "update", "search"];
 export type VeterinaryResearchStudyPermissionAction = typeof VeterinaryResearchStudyPermissionActions[number];
 export declare const VeterinaryResearchStudyInvitationClaimNames: Readonly<{
     readonly Context: "@context";
-    readonly Status: "Consent.status";
-    readonly Decision: "Consent.decision";
-    readonly ActorIdentifier: "Consent.actor-identifier";
-    readonly Purpose: "Consent.purpose";
-    readonly Action: "Consent.action";
-    readonly ResourceType: "Consent.resource-type";
+    readonly Status: ClaimConsent.status;
+    readonly Decision: ClaimConsent.decision;
+    readonly ActorIdentifier: ClaimConsent.actorIdentifier;
+    readonly Purpose: ClaimConsent.purpose;
+    readonly Action: ClaimConsent.action;
+    readonly ResourceType: ClaimConsent.resourceType;
 }>;
 type FhirReference = Readonly<{
     reference: string;
@@ -97,11 +101,58 @@ export type VeterinaryResearchStudyBatchEntry = Readonly<{
 export type VeterinaryResearchStudyBatch = Readonly<{
     data: readonly VeterinaryResearchStudyBatchEntry[];
 }>;
+export type VeterinaryResearchStudyGroupResource = GroupR5ResearchTeam & Readonly<{
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, readonly string[]>>;
+        [key: string]: unknown;
+    }>;
+}>;
+export type VeterinaryResearchStudyGroupBatchEntry = Readonly<{
+    type: 'Group-v5.0.0';
+    resource: VeterinaryResearchStudyGroupResource;
+    request: Readonly<{
+        method: 'POST' | 'PATCH';
+        url: string;
+    }>;
+}>;
+export type VeterinaryResearchStudyGroupBatch = Readonly<{
+    data: readonly VeterinaryResearchStudyGroupBatchEntry[];
+}>;
 export type VeterinaryResearchStudySmartAuthorization = Readonly<{
-    purpose: 'RESEARCH';
+    purpose: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
     scopes: readonly [string];
 }>;
+export type VeterinaryResearchStudyActiveConsentInput = Readonly<{
+    consentId: string;
+    researchStudyId: string;
+    practitionerRoleId: string;
+    actorRole: `ISCO-08|${string}`;
+    date: string;
+    status?: typeof ConsentStatuses.Active;
+}>;
+export type VeterinaryResearchStudyActiveConsent = Readonly<{
+    resourceType: typeof ResourceTypesFhirR5.Consent;
+    id: string;
+    status: typeof ConsentStatuses.Active;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+export type VeterinaryResearchStudyActiveConsentEntry = Readonly<{
+    type: 'Consent-v5.0.0';
+    resource: VeterinaryResearchStudyActiveConsent;
+    request: Readonly<{
+        method: 'POST';
+        url: typeof ResourceTypesFhirR5.Consent;
+    }>;
+}>;
+export type VeterinaryResearchStudyActiveConsentBatch = Readonly<{
+    data: readonly VeterinaryResearchStudyActiveConsentEntry[];
+}>;
+/** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
+export declare function buildVeterinaryResearchStudyAccessScope(researchStudyId: string): string;
 /**
  * Requests the current study-scoped ResearchSubject operations. Deleting
  * selected clinical facts is a later operation on those concrete resources;
@@ -112,7 +163,73 @@ export declare function buildVeterinaryResearchStudySmartAuthorization(input: Re
     dcrCompleted: boolean;
     consentStatus: 'draft' | 'active' | 'inactive' | 'not-done' | 'entered-in-error' | 'unknown';
 }>): VeterinaryResearchStudySmartAuthorization;
+/**
+ * Builds controller decisions for the VET ResearchStudy Consent `_batch`.
+ * Every entry is an explicit active/permit decision for one DCR-bound
+ * PractitionerRole. Invitation drafts, descriptive Group membership and
+ * `ResearchStudy.associatedParty` never authorize. The only action is the
+ * exact study-scoped ResearchSubject create/read/update/search capability;
+ * delete is deliberately absent.
+ *
+ * `subjectDid` is deliberately absent from the matching SMART authorization:
+ * the high-level professional runtime supplies the DCR-bound actor as `sub`,
+ * while GW derives the ResearchStudy authorization subject from this scope.
+ *
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ */
+export declare function buildVeterinaryResearchStudyActiveConsentBatch(inputs: readonly VeterinaryResearchStudyActiveConsentInput[]): VeterinaryResearchStudyActiveConsentBatch;
+/** Builds one POST Consent entry accepted by the VET ResearchStudy manager. */
+export declare function buildVeterinaryResearchStudyActiveConsentEntry(input: VeterinaryResearchStudyActiveConsentInput): VeterinaryResearchStudyActiveConsentEntry;
 export declare function buildVeterinaryResearchStudyBatch(entries: readonly VeterinaryResearchStudyBatchEntry[]): VeterinaryResearchStudyBatch;
+/**
+ * Returns the native eligibility reference by which an R5 ResearchStudy links
+ * to its descriptive professional Group. The direction is deliberately from
+ * `ResearchStudy.recruitment.eligibility` to Group; no invented study field or
+ * search claim is added to Group.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/group.html
+ */
+export declare function buildVeterinaryResearchStudyEligibilityGroupReference(groupId: string): Readonly<{
+    reference: `Group/${string}`;
+    type: 'Group';
+}>;
+/**
+ * Builds the native ResearchStudy PATCH that links a descriptive Group through
+ * `ResearchStudy.recruitment.eligibility`. The existing ResearchStudy batch
+ * builder wraps this entry; Group and ResearchStudy remain separate resource
+ * endpoints and no mixed-resource transport envelope is invented.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export declare function buildVeterinaryResearchStudyEligibilityGroupPatchEntry(input: Readonly<{
+    researchStudyId: string;
+    groupId: string;
+}>): VeterinaryResearchStudyBatchEntry;
+/**
+ * Builds the Group POST used to create one enumerated ResearchStudy review
+ * team. Every member is a native PractitionerRole reference. Group remains a
+ * description only and the generated resource cannot carry access policy.
+ *
+ * @see https://hl7.org/fhir/R5/group.html
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export declare function buildVeterinaryResearchStudyGroupCreateEntry(input: Readonly<{
+    group: GroupR5ResearchTeam;
+}>): VeterinaryResearchStudyGroupBatchEntry;
+/**
+ * Builds one independently correlated PATCH per PractitionerRole member. A
+ * PATCH changes descriptive membership only; DCR, Consent and SMART remain
+ * separate authorization boundaries.
+ */
+export declare function buildVeterinaryResearchStudyGroupMemberPatchEntries(input: Readonly<{
+    groupId: string;
+    members: unknown;
+}>): readonly VeterinaryResearchStudyGroupBatchEntry[];
+/** Wraps only validated Group POST/PATCH entries in one JSON:API document. */
+export declare function buildVeterinaryResearchStudyGroupBatch(entries: readonly VeterinaryResearchStudyGroupBatchEntry[]): VeterinaryResearchStudyGroupBatch;
 export declare function buildVeterinaryResearchStudyCreateEntry(input: Readonly<{
     study: VeterinaryResearchStudyCreateResource;
 }>): VeterinaryResearchStudyBatchEntry;

package/dist/research-study.js

@@ -1,5 +1,10 @@
 import { normalizeResearchStudyAssociatedParties, projectResearchStudyAssociatedPartyClaims, projectResearchStudyR5SearchClaims, } from 'vet-data-utils-ts/research-study';
 import { VeterinaryCommunicationPresetFilters, VeterinaryResearchCommunicationTopics, } from 'vet-data-utils-ts/communication';
+import { normalizeGroupPractitionerRoleMembers, normalizeGroupR5ResearchTeam, projectGroupR5SearchClaims, } from 'vet-data-utils-ts/group';
+import { HealthcareConsentPurposes } from 'gdc-common-utils-ts/constants/healthcare';
+import { ResourceTypesFhirR5 } from 'gdc-common-utils-ts/constants/fhir-resource-types';
+import { InteroperableContext } from 'gdc-common-utils-ts/constants/lifecycle';
+import { ClaimConsent, ConsentDecisions, ConsentStatuses, } from 'gdc-common-utils-ts/models/consent-rule';
 const FHIR_RESTFUL_INTERACTION_SYSTEM = 'http://hl7.org/fhir/restful-interaction';
 const FHIR_RESOURCE_TYPES_SYSTEM = 'http://hl7.org/fhir/fhir-types';
 export const VeterinaryResearchStudyPermissionActions = Object.freeze([
@@ -10,13 +15,17 @@ export const VeterinaryResearchStudyPermissionActions = Object.freeze([
 ]);
 export const VeterinaryResearchStudyInvitationClaimNames = Object.freeze({
     Context: '@context',
-    Status: 'Consent.status',
-    Decision: 'Consent.decision',
-    ActorIdentifier: 'Consent.actor-identifier',
-    Purpose: 'Consent.purpose',
-    Action: 'Consent.action',
-    ResourceType: 'Consent.resource-type',
+    Status: ClaimConsent.status,
+    Decision: ClaimConsent.decision,
+    ActorIdentifier: ClaimConsent.actorIdentifier,
+    Purpose: ClaimConsent.purpose,
+    Action: ClaimConsent.action,
+    ResourceType: ClaimConsent.resourceType,
 });
+/** Builds the exact GW study-pinned ResearchSubject `crus` capability. */
+export function buildVeterinaryResearchStudyAccessScope(researchStudyId) {
+    return `organization/ResearchSubject.crus?study=ResearchStudy/${boundedId(researchStudyId)}`;
+}
 /**
  * Requests the current study-scoped ResearchSubject operations. Deleting
  * selected clinical facts is a later operation on those concrete resources;
@@ -31,9 +40,70 @@ export function buildVeterinaryResearchStudySmartAuthorization(input) {
     }
     const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
     return deepFreeze({
-        purpose: 'RESEARCH',
+        purpose: HealthcareConsentPurposes.Research,
         researchStudyReference,
-        scopes: [`organization/ResearchSubject.crus?study=${encodeURIComponent(researchStudyReference)}`],
+        // This is a SMART scope value, not a URL query assembled by the browser.
+        // Encoding the slash would no longer equal the active Consent action.
+        scopes: [buildVeterinaryResearchStudyAccessScope(input.researchStudyId)],
+    });
+}
+/**
+ * Builds controller decisions for the VET ResearchStudy Consent `_batch`.
+ * Every entry is an explicit active/permit decision for one DCR-bound
+ * PractitionerRole. Invitation drafts, descriptive Group membership and
+ * `ResearchStudy.associatedParty` never authorize. The only action is the
+ * exact study-scoped ResearchSubject create/read/update/search capability;
+ * delete is deliberately absent.
+ *
+ * `subjectDid` is deliberately absent from the matching SMART authorization:
+ * the high-level professional runtime supplies the DCR-bound actor as `sub`,
+ * while GW derives the ResearchStudy authorization subject from this scope.
+ *
+ * @see https://hl7.org/fhir/R5/consent.html
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ */
+export function buildVeterinaryResearchStudyActiveConsentBatch(inputs) {
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+        throw new TypeError('veterinary_research_study_active_consent_batch_empty');
+    }
+    const data = inputs.map(buildVeterinaryResearchStudyActiveConsentEntry);
+    return deepFreeze({ data });
+}
+/** Builds one POST Consent entry accepted by the VET ResearchStudy manager. */
+export function buildVeterinaryResearchStudyActiveConsentEntry(input) {
+    if (input.status !== undefined && input.status !== ConsentStatuses.Active) {
+        throw new TypeError('veterinary_research_study_active_consent_status_invalid');
+    }
+    const consentId = boundedId(input.consentId);
+    const researchStudyReference = `ResearchStudy/${boundedId(input.researchStudyId)}`;
+    const practitionerRoleReference = `PractitionerRole/${boundedId(input.practitionerRoleId)}`;
+    const actorRole = String(input.actorRole || '').trim();
+    if (!/^ISCO-08\|[0-9]{1,4}$/.test(actorRole)) {
+        throw new TypeError('veterinary_research_study_active_consent_actor_role_invalid');
+    }
+    const date = boundedDate(input.date);
+    const action = buildVeterinaryResearchStudyAccessScope(input.researchStudyId);
+    return deepFreeze({
+        type: 'Consent-v5.0.0',
+        resource: {
+            resourceType: ResourceTypesFhirR5.Consent,
+            id: consentId,
+            status: ConsentStatuses.Active,
+            meta: {
+                claims: {
+                    '@context': InteroperableContext.FhirApi,
+                    [ClaimConsent.status]: ConsentStatuses.Active,
+                    [ClaimConsent.decision]: ConsentDecisions.Permit,
+                    [ClaimConsent.purpose]: HealthcareConsentPurposes.Research,
+                    [ClaimConsent.sourceReference]: researchStudyReference,
+                    [ClaimConsent.actorIdentifier]: practitionerRoleReference,
+                    [ClaimConsent.actorRole]: actorRole,
+                    [ClaimConsent.action]: action,
+                    [ClaimConsent.date]: date,
+                },
+            },
+        },
+        request: { method: 'POST', url: ResourceTypesFhirR5.Consent },
     });
 }
 export function buildVeterinaryResearchStudyBatch(entries) {
@@ -41,6 +111,86 @@ export function buildVeterinaryResearchStudyBatch(entries) {
         throw new TypeError('veterinary_research_study_batch_empty');
     return deepFreeze({ data: entries.map(entry => clonePlain(entry)) });
 }
+/**
+ * Returns the native eligibility reference by which an R5 ResearchStudy links
+ * to its descriptive professional Group. The direction is deliberately from
+ * `ResearchStudy.recruitment.eligibility` to Group; no invented study field or
+ * search claim is added to Group.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/group.html
+ */
+export function buildVeterinaryResearchStudyEligibilityGroupReference(groupId) {
+    return deepFreeze({ reference: `Group/${boundedGroupId(groupId)}`, type: 'Group' });
+}
+/**
+ * Builds the native ResearchStudy PATCH that links a descriptive Group through
+ * `ResearchStudy.recruitment.eligibility`. The existing ResearchStudy batch
+ * builder wraps this entry; Group and ResearchStudy remain separate resource
+ * endpoints and no mixed-resource transport envelope is invented.
+ *
+ * @see https://hl7.org/fhir/R5/researchstudy.html
+ * @see https://hl7.org/fhir/R5/researchstudy-search.html
+ */
+export function buildVeterinaryResearchStudyEligibilityGroupPatchEntry(input) {
+    if (containsAuthorizationProperty(input)) {
+        throw new TypeError('veterinary_research_study_group_authorization_forbidden');
+    }
+    const researchStudyId = boundedId(input.researchStudyId);
+    const eligibility = buildVeterinaryResearchStudyEligibilityGroupReference(input.groupId);
+    return deepFreeze({
+        type: 'ResearchStudy-v5.0.0',
+        resource: withProjectedClaims({
+            resourceType: 'ResearchStudy',
+            id: researchStudyId,
+            recruitment: { eligibility },
+        }),
+        request: { method: 'PATCH', url: `ResearchStudy/${researchStudyId}` },
+    });
+}
+/**
+ * Builds the Group POST used to create one enumerated ResearchStudy review
+ * team. Every member is a native PractitionerRole reference. Group remains a
+ * description only and the generated resource cannot carry access policy.
+ *
+ * @see https://hl7.org/fhir/R5/group.html
+ * @see https://hl7.org/fhir/R5/group-search.html
+ */
+export function buildVeterinaryResearchStudyGroupCreateEntry(input) {
+    const group = normalizedResearchTeamGroup(input.group);
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(group),
+        request: { method: 'POST', url: 'Group' },
+    });
+}
+/**
+ * Builds one independently correlated PATCH per PractitionerRole member. A
+ * PATCH changes descriptive membership only; DCR, Consent and SMART remain
+ * separate authorization boundaries.
+ */
+export function buildVeterinaryResearchStudyGroupMemberPatchEntries(input) {
+    const id = boundedGroupId(input.groupId);
+    const members = normalizeGroupPractitionerRoleMembers(input.members);
+    return deepFreeze(members.map(member => ({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(deepFreeze({
+            resourceType: 'Group',
+            id,
+            type: 'practitioner',
+            membership: 'enumerated',
+            member: [member],
+        })),
+        request: { method: 'PATCH', url: `Group/${id}` },
+    })));
+}
+/** Wraps only validated Group POST/PATCH entries in one JSON:API document. */
+export function buildVeterinaryResearchStudyGroupBatch(entries) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new TypeError('veterinary_research_study_group_batch_empty');
+    }
+    return deepFreeze({ data: entries.map(normalizeResearchStudyGroupEntry) });
+}
 export function buildVeterinaryResearchStudyCreateEntry(input) {
     const study = normalizedStudy(input.study);
     return deepFreeze({
@@ -221,6 +371,37 @@ function normalizedStudy(input) {
         ...(associatedParty ? { associatedParty } : {}),
     });
 }
+function normalizedResearchTeamGroup(input) {
+    const source = clonePlain(input);
+    const normalized = normalizeGroupR5ResearchTeam(source);
+    return deepFreeze({ ...normalized, id: boundedGroupId(normalized.id) });
+}
+function normalizeResearchStudyGroupEntry(input) {
+    if (!input || input.type !== 'Group-v5.0.0') {
+        throw new TypeError('veterinary_research_study_group_entry_invalid');
+    }
+    const group = normalizedResearchTeamGroup(input.resource);
+    const method = input.request?.method;
+    const expectedUrl = method === 'POST' ? 'Group' : method === 'PATCH' ? `Group/${group.id}` : '';
+    if (!expectedUrl || input.request.url !== expectedUrl) {
+        throw new TypeError('veterinary_research_study_group_request_invalid');
+    }
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource: withProjectedGroupClaims(group),
+        request: { method, url: expectedUrl },
+    });
+}
+function withProjectedGroupClaims(group) {
+    const claims = projectGroupR5SearchClaims(group);
+    return deepFreeze({
+        ...group,
+        meta: {
+            ...(typeof group.meta === 'object' && group.meta !== null ? group.meta : {}),
+            claims,
+        },
+    });
+}
 function clonePlain(value) {
     if (Array.isArray(value))
         return value.map(clonePlain);
@@ -256,6 +437,12 @@ function boundedId(value) {
         throw new TypeError('veterinary_research_study_id_invalid');
     return id;
 }
+function boundedGroupId(value) {
+    const id = String(value || '').trim();
+    if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
+        throw new TypeError('veterinary_research_study_group_id_invalid');
+    return id;
+}
 function boundedReference(value, resourceType) {
     const reference = String(value || '').trim();
     const prefix = `${resourceType}/`;
@@ -264,6 +451,17 @@ function boundedReference(value, resourceType) {
     boundedId(reference.slice(prefix.length));
     return reference;
 }
+function boundedDate(value) {
+    const date = String(value || '').trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new TypeError('veterinary_research_study_active_consent_date_invalid');
+    }
+    const parsed = new Date(`${date}T00:00:00Z`);
+    if (!Number.isFinite(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== date) {
+        throw new TypeError('veterinary_research_study_active_consent_date_invalid');
+    }
+    return date;
+}
 function optionalInstant(value) {
     const instant = String(value || '').trim();
     if (!instant)
@@ -272,6 +470,16 @@ function optionalInstant(value) {
         throw new TypeError('veterinary_research_study_invitation_sent_invalid');
     return instant;
 }
+function containsAuthorizationProperty(value, seen = new WeakSet()) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.some(item => containsAuthorizationProperty(item, seen));
+    return Object.entries(value).some(([name, nested]) => ['authorization', 'permission', 'scope'].includes(name) || containsAuthorizationProperty(nested, seen));
+}
 function splitCodingToken(value) {
     const separator = value.lastIndexOf('|');
     if (separator < 1 || separator === value.length - 1) {

package/docs/101-RESEARCH-STUDY-INVITATIONS.md

@@ -16,10 +16,40 @@ related to the exact ResearchStudy. Whole-twin delete is absent.
 
 ```ts
 import {
+  buildVeterinaryResearchStudyActiveConsentBatch,
+  buildVeterinaryResearchStudyBatch,
+  buildVeterinaryResearchStudyEligibilityGroupPatchEntry,
+  buildVeterinaryResearchStudyGroupBatch,
+  buildVeterinaryResearchStudyGroupCreateEntry,
+  buildVeterinaryResearchStudyGroupMemberPatchEntries,
   buildVeterinaryResearchStudyPartyInvitations,
   buildVeterinaryResearchStudySmartAuthorization,
 } from 'vet-sdk-core-ts/research-study'
 
+const researchGroupId = 'review-team'
+const groupCreate = buildVeterinaryResearchStudyGroupCreateEntry({
+  group: {
+    resourceType: 'Group',
+    id: researchGroupId,
+    type: 'practitioner',
+    membership: 'enumerated',
+    member: [],
+  },
+})
+const memberPatches = buildVeterinaryResearchStudyGroupMemberPatchEntries({
+  groupId: researchGroupId,
+  members: associatedParties.map(({ party }) => ({ entity: party })),
+})
+const groupBatch = buildVeterinaryResearchStudyGroupBatch([groupCreate, ...memberPatches])
+// The protected controller BFF submits `groupBatch`; membership grants no access.
+const eligibilityPatch = buildVeterinaryResearchStudyEligibilityGroupPatchEntry({
+  researchStudyId: study.id,
+  groupId: researchGroupId,
+})
+const studyPatchBatch = buildVeterinaryResearchStudyBatch([eligibilityPatch])
+// Submit `studyPatchBatch` through the protected ResearchStudy BFF after the
+// Group exists. The two native resource endpoints remain separate.
+
 const invitations = buildVeterinaryResearchStudyPartyInvitations({
   researchStudyId: study.id,
   controllerReference: organizationReference,
@@ -37,6 +67,18 @@ for (const communication of invitations) {
   await professionalRuntime.ingestCommunicationAndUpdateIndex({ communication })
 }
 
+// Once DCR is confirmed, the controller persists a new active Consent. This
+// is separate from the draft inside Communication and is the actual grant.
+const activeConsentBatch = buildVeterinaryResearchStudyActiveConsentBatch([{
+  consentId: activeConsentId,
+  researchStudyId: study.id,
+  practitionerRoleId: protectedProfessional.practitionerRoleId,
+  actorRole: protectedProfessional.iscoRole,
+  date: new Date().toISOString().slice(0, 10),
+}])
+// The protected BFF submits this primary document to the tenant organization
+// FHIR R5 Consent/_batch boundary; the browser never authors that route.
+
 // This succeeds only after protected state proves both prerequisites. Browser
 // input must not be trusted as that proof.
 const authorization = buildVeterinaryResearchStudySmartAuthorization({
@@ -47,6 +89,24 @@ const authorization = buildVeterinaryResearchStudySmartAuthorization({
 await professionalRuntime.requestSmartToken(authorization)
 ```
 
+The controller may also create a descriptive review team with
+`buildVeterinaryResearchStudyGroupCreateEntry()` and append each registered
+`PractitionerRole` with
+`buildVeterinaryResearchStudyGroupMemberPatchEntries()`. The Group is linked
+from `ResearchStudy.recruitment.eligibility` using
+`buildVeterinaryResearchStudyEligibilityGroupPatchEntry()` and the existing
+ResearchStudy batch builder. Group membership is not evidence of DCR or
+Consent and never grants the SMART authorization above.
+
+These builders follow the native [FHIR R5 Group resource](https://hl7.org/fhir/R5/group.html)
+and its exact [resource-specific search catalogue](https://hl7.org/fhir/R5/group-search.html).
+
+The SMART authorization intentionally does not carry `subjectDid`:
+`openProfessional()` supplies its DCR-bound actor as `sub`, while GW derives
+the authorization subject `ResearchStudy/<id>` from the exact unescaped scope.
+Percent-encoding the `/` in that scope would no longer match the active
+Consent action and is rejected.
+
 The Bundle is encoded as the standard
 `Communication.payload.contentAttachment` with
 `contentType = application/fhir+json`. The Consent uses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-sdk-core-ts",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Browser-safe VetChain core contracts and governed animal species identifiers",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -63,6 +63,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
-    "vet-data-utils-ts": "0.5.0"
+    "gdc-common-utils-ts": "2.9.4",
+    "vet-data-utils-ts": "0.5.1"
   }
 }