vet-sdk-core-ts 0.4.12 → 0.4.14

package/README.md

@@ -8,12 +8,13 @@ owns gateway request construction. GW VET remains the policy authority.
 
 ## Research studies
 
-`buildVeterinaryResearchStudyCreateEntry` preserves a native FHIR R5
-ResearchStudy and derives its standard flat search claims. Associated parties
-are retained as complete objects. Later changes use one independent PATCH
-entry per party, so the party reference, role, periods and classifiers cannot
-be mixed across employees. `buildVeterinaryResearchStudyBatch` wraps these
-entries in JSON:API `data[]` for GW VET.
+`buildVeterinaryResearchStudyCreateEntry` accepts ResearchStudy business data
+and projects it into the canonical JSON:API resource object: `resourceType`,
+`id` and flat `resource.meta.claims`. It does not send native `status`, `title`,
+`associatedParty` or `recruitment` objects to GW. Associated parties use one
+independent flat-claim PATCH entry per party, so references, roles, periods and
+classifiers cannot be mixed across employees. Native FHIR JSON is produced
+only by an explicit later export/projection boundary.
 
 Study participation does not itself authorize access. The separate
 `buildVeterinaryResearchStudySmartAuthorization` request is limited to create,
@@ -33,13 +34,25 @@ separate JSON:API `Consent/_batch`. Every POST is fixed to `active`, `permit`,
 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
-an `application/fhir+json` batch Bundle with exactly one draft Consent, scoped
-to the ResearchStudy through `Consent.provision.data.reference` and to
-`ResearchSubject` through `Consent.provision.resourceType`. The draft requests
-only create, read, update and search. It contains no delete permission and
-never authorizes SMART access.
+`buildVeterinaryResearchStudyPartyInvitations` creates exactly one claims-only
+`Communication` per associated `PractitionerRole`. Its canonical attachment
+claims carry an `application/vnd.api+json` primary document containing one
+claims-only draft Consent. `Consent.source-reference` pins the ResearchStudy
+and `Consent.resource-type` pins `ResearchSubject`. The draft requests only
+create, read, update and search; it contains no delete permission and never
+authorizes SMART access. Native FHIR Communication, Consent or Bundle objects
+are accepted only by explicit import/projection/export adapters.
+
+`buildVeterinaryResearchStudyGroupCreateEntry` and
+`buildVeterinaryResearchStudyGroupMemberPatchEntries` build flat-claim 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`, and each member has its own PATCH entry.
+The Group stays independent: individual professionals are related to the study
+through separate `ResearchStudy.associatedParty` PATCH entries. It must not use
+`ResearchStudy.recruitment.eligibility`, which represents research-subject
+cohorts or eligibility criteria. Group grants no authorization, permission or
+SMART scope; DCR and active Consent remain separate.
 
 The complete controller-to-professional contract and a browser-safe snippet
 are in
@@ -51,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,4 +1,5 @@
-import { type ResearchStudyAssociatedParty } from 'vet-data-utils-ts/research-study';
+import { type ResearchStudyAssociatedParty, type ResearchStudyR5FlatClaimsResource } from 'vet-data-utils-ts/research-study';
+import { type GroupR5FlatClaimsResource, 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';
@@ -13,46 +14,16 @@ export declare const VeterinaryResearchStudyInvitationClaimNames: Readonly<{
     readonly Action: ClaimConsent.action;
     readonly ResourceType: ClaimConsent.resourceType;
 }>;
-type FhirReference = Readonly<{
-    reference: string;
-    type?: string;
-}>;
-type FhirCoding = Readonly<{
-    system: string;
-    code: string;
-}>;
-type FhirCodeableConcept = Readonly<{
-    coding: readonly FhirCoding[];
-}>;
 export type VeterinaryResearchStudyDraftConsent = Readonly<{
     resourceType: 'Consent';
     id: string;
-    status: 'draft';
-    grantor: readonly FhirReference[];
-    controller: readonly FhirReference[];
-    grantee: readonly FhirReference[];
-    decision: 'permit';
-    provision: readonly Readonly<{
-        actor: readonly Readonly<{
-            reference: FhirReference;
-        }>[];
-        action: readonly FhirCodeableConcept[];
-        purpose: readonly FhirCoding[];
-        resourceType: readonly FhirCoding[];
-        data: readonly Readonly<{
-            meaning: 'related';
-            reference: FhirReference;
-        }>[];
-    }>[];
     meta: Readonly<{
         claims: Readonly<Record<string, string>>;
     }>;
 }>;
-export type VeterinaryResearchStudyInvitationBundle = Readonly<{
-    resourceType: 'Bundle';
-    type: 'batch';
-    entry: readonly Readonly<{
-        fullUrl: string;
+export type VeterinaryResearchStudyInvitationDocument = Readonly<{
+    data: readonly Readonly<{
+        type: 'Consent-v5.0.0';
         resource: VeterinaryResearchStudyDraftConsent;
         request: Readonly<{
             method: 'POST';
@@ -63,22 +34,12 @@ export type VeterinaryResearchStudyInvitationBundle = Readonly<{
 export type VeterinaryResearchStudyPartyInvitation = Readonly<{
     resourceType: 'Communication';
     id: string;
-    status: 'completed';
-    category: readonly FhirCodeableConcept[];
-    topic: FhirCodeableConcept;
-    about: readonly FhirReference[];
-    recipient: readonly FhirReference[];
-    sender: FhirReference;
-    sent?: string;
-    payload: readonly Readonly<{
-        contentAttachment: Readonly<{
-            contentType: 'application/fhir+json';
-            title: 'research-study-draft-consent.json';
-            data: string;
-        }>;
-    }>[];
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
 }>;
-export type VeterinaryResearchStudyResource = Readonly<{
+/** Native-shaped builder input used only to derive the persisted flat claims. */
+export type VeterinaryResearchStudySourceResource = Readonly<{
     resourceType: 'ResearchStudy';
     id: string;
     status?: 'draft' | 'active' | 'retired' | 'unknown';
@@ -86,9 +47,10 @@ export type VeterinaryResearchStudyResource = Readonly<{
     meta?: Readonly<Record<string, unknown>>;
     [key: string]: unknown;
 }>;
-export type VeterinaryResearchStudyCreateResource = VeterinaryResearchStudyResource & Readonly<{
-    status: NonNullable<VeterinaryResearchStudyResource['status']>;
+export type VeterinaryResearchStudyCreateResource = VeterinaryResearchStudySourceResource & Readonly<{
+    status: NonNullable<VeterinaryResearchStudySourceResource['status']>;
 }>;
+export type VeterinaryResearchStudyResource = ResearchStudyR5FlatClaimsResource;
 export type VeterinaryResearchStudyBatchEntry = Readonly<{
     type: 'ResearchStudy-v5.0.0';
     resource: VeterinaryResearchStudyResource;
@@ -100,6 +62,18 @@ export type VeterinaryResearchStudyBatchEntry = Readonly<{
 export type VeterinaryResearchStudyBatch = Readonly<{
     data: readonly VeterinaryResearchStudyBatchEntry[];
 }>;
+export type VeterinaryResearchStudyGroupResource = GroupR5FlatClaimsResource;
+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: typeof HealthcareConsentPurposes.Research;
     researchStudyReference: string;
@@ -116,7 +90,6 @@ export type VeterinaryResearchStudyActiveConsentInput = Readonly<{
 export type VeterinaryResearchStudyActiveConsent = Readonly<{
     resourceType: typeof ResourceTypesFhirR5.Consent;
     id: string;
-    status: typeof ConsentStatuses.Active;
     meta: Readonly<{
         claims: Readonly<Record<string, string>>;
     }>;
@@ -160,16 +133,39 @@ export declare function buildVeterinaryResearchStudySmartAuthorization(input: Re
  * @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. */
+/** Builds one flat-claims POST Consent entry accepted by the VET ResearchStudy manager. */
 export declare function buildVeterinaryResearchStudyActiveConsentEntry(input: VeterinaryResearchStudyActiveConsentInput): VeterinaryResearchStudyActiveConsentEntry;
 export declare function buildVeterinaryResearchStudyBatch(entries: readonly VeterinaryResearchStudyBatchEntry[]): VeterinaryResearchStudyBatch;
+/**
+ * Builds the flat-claims Group POST used to create one enumerated ResearchStudy
+ * review team. Every member is added later as its own PractitionerRole claim
+ * PATCH. Group remains a description only and 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;
 /**
  * Builds one independent `_batch` PATCH entry per R5 associatedParty. Keeping
- * each complete party in its own entry prevents roles, periods and classifiers
- * from being correlated with the wrong PractitionerRole. These entries update
+ * each party's claim map in its own entry prevents roles, periods and
+ * classifiers from being correlated with the wrong PractitionerRole. Native
+ * `associatedParty` JSON is not sent to persistence. These entries update
  * study membership only; they do not grant CRUDS access.
  */
 export declare function buildVeterinaryResearchStudyPartyPatchEntries(input: Readonly<{
@@ -178,17 +174,15 @@ export declare function buildVeterinaryResearchStudyPartyPatchEntries(input: Rea
 }>): readonly VeterinaryResearchStudyBatchEntry[];
 /**
  * Builds the auditable R5 invitation sent to one ResearchStudy associated
- * party. The Communication payload is an `application/fhir+json` attachment
- * containing a batch Bundle with exactly one `Consent.status = draft`.
+ * party. The claims-only Communication carries an `application/vnd.api+json`
+ * primary document with exactly one claims-only `Consent.status = draft`.
  * Draft is descriptive only and can never satisfy authorization. The invitee
  * must finish DCR and a controller must later persist a separate active
  * Consent before the study-scoped SMART request can succeed.
  *
- * Native R5 fields retain the exact study boundary in
- * `Consent.provision.data.reference` and the affected `ResearchSubject`
- * resource family. Project authorization actions remain create/read/update/
- * search; their FHIR representation uses the matching REST interaction codes,
- * where search is `search-type`. Delete is deliberately absent.
+ * The flat Consent claims retain the exact study boundary and affected
+ * `ResearchSubject` resource family. Delete is deliberately absent. Native
+ * FHIR projection belongs only at an explicit import/export boundary.
  *
  * @see https://hl7.org/fhir/R5/communication.html
  * @see https://hl7.org/fhir/R5/consent.html
@@ -217,6 +211,5 @@ export declare function buildVeterinaryResearchStudyPartyInvitations(input: Read
         consentId: string;
     }>[];
 }>): readonly VeterinaryResearchStudyPartyInvitation[];
-/** Decodes the single attached Consent Bundle after validating its boundary. */
-export declare function decodeVeterinaryResearchStudyInvitationBundle(communication: VeterinaryResearchStudyPartyInvitation): VeterinaryResearchStudyInvitationBundle;
-export {};
+/** Decodes the attached JSON:API Consent document after validating its claims-only boundary. */
+export declare function decodeVeterinaryResearchStudyInvitationDocument(communication: VeterinaryResearchStudyPartyInvitation): VeterinaryResearchStudyInvitationDocument;

package/dist/research-study.js

@@ -1,11 +1,12 @@
-import { normalizeResearchStudyAssociatedParties, projectResearchStudyAssociatedPartyClaims, projectResearchStudyR5SearchClaims, } from 'vet-data-utils-ts/research-study';
+import { normalizeResearchStudyAssociatedParties, normalizeResearchStudyR5FlatClaimsResource, projectResearchStudyAssociatedPartyFlatClaimResources, projectResearchStudyR5FlatClaimsResource, } from 'vet-data-utils-ts/research-study';
 import { VeterinaryCommunicationPresetFilters, VeterinaryResearchCommunicationTopics, } from 'vet-data-utils-ts/communication';
+import { normalizeGroupR5FlatClaimsResource, normalizeGroupR5ResearchTeam, projectGroupPractitionerRoleMemberFlatClaimResources, projectGroupR5FlatClaimsResource, } from 'vet-data-utils-ts/group';
+import { HttpMediaTypes } from 'gdc-common-utils-ts/constants/http';
 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';
+import { CommunicationClaim } from 'gdc-common-utils-ts/models/interoperable-claims/communication-claims';
 export const VeterinaryResearchStudyPermissionActions = Object.freeze([
     'create',
     'read',
@@ -68,7 +69,7 @@ export function buildVeterinaryResearchStudyActiveConsentBatch(inputs) {
     const data = inputs.map(buildVeterinaryResearchStudyActiveConsentEntry);
     return deepFreeze({ data });
 }
-/** Builds one POST Consent entry accepted by the VET ResearchStudy manager. */
+/** Builds one flat-claims 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');
@@ -87,7 +88,6 @@ export function buildVeterinaryResearchStudyActiveConsentEntry(input) {
         resource: {
             resourceType: ResourceTypesFhirR5.Consent,
             id: consentId,
-            status: ConsentStatuses.Active,
             meta: {
                 claims: {
                     '@context': InteroperableContext.FhirApi,
@@ -108,48 +108,85 @@ export function buildVeterinaryResearchStudyActiveConsentEntry(input) {
 export function buildVeterinaryResearchStudyBatch(entries) {
     if (!Array.isArray(entries) || entries.length === 0)
         throw new TypeError('veterinary_research_study_batch_empty');
-    return deepFreeze({ data: entries.map(entry => clonePlain(entry)) });
+    return deepFreeze({ data: entries.map(normalizeResearchStudyBatchEntry) });
+}
+/**
+ * Builds the flat-claims Group POST used to create one enumerated ResearchStudy
+ * review team. Every member is added later as its own PractitionerRole claim
+ * PATCH. Group remains a description only and 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);
+    if (group.member.length > 0)
+        throw new TypeError('group_members_require_patch_entries');
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource: projectGroupR5FlatClaimsResource(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 resources = projectGroupPractitionerRoleMemberFlatClaimResources({ groupId: id, members: input.members });
+    return deepFreeze(resources.map(resource => ({
+        type: 'Group-v5.0.0',
+        resource,
+        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({
         type: 'ResearchStudy-v5.0.0',
-        resource: withProjectedClaims(study),
+        resource: projectResearchStudyR5FlatClaimsResource(study),
         request: { method: 'POST', url: 'ResearchStudy' },
     });
 }
 /**
  * Builds one independent `_batch` PATCH entry per R5 associatedParty. Keeping
- * each complete party in its own entry prevents roles, periods and classifiers
- * from being correlated with the wrong PractitionerRole. These entries update
+ * each party's claim map in its own entry prevents roles, periods and
+ * classifiers from being correlated with the wrong PractitionerRole. Native
+ * `associatedParty` JSON is not sent to persistence. These entries update
  * study membership only; they do not grant CRUDS access.
  */
 export function buildVeterinaryResearchStudyPartyPatchEntries(input) {
     const id = boundedId(input.researchStudyId);
-    const parties = normalizeResearchStudyAssociatedParties(input.associatedParties);
-    return deepFreeze(parties.map(party => ({
+    const resources = projectResearchStudyAssociatedPartyFlatClaimResources({
+        researchStudyId: id,
+        associatedParties: input.associatedParties,
+    });
+    return deepFreeze(resources.map(resource => ({
         type: 'ResearchStudy-v5.0.0',
-        resource: withProjectedClaims({
-            resourceType: 'ResearchStudy',
-            id,
-            associatedParty: [party],
-        }),
+        resource,
         request: { method: 'PATCH', url: `ResearchStudy/${id}` },
     })));
 }
 /**
  * Builds the auditable R5 invitation sent to one ResearchStudy associated
- * party. The Communication payload is an `application/fhir+json` attachment
- * containing a batch Bundle with exactly one `Consent.status = draft`.
+ * party. The claims-only Communication carries an `application/vnd.api+json`
+ * primary document with exactly one claims-only `Consent.status = draft`.
  * Draft is descriptive only and can never satisfy authorization. The invitee
  * must finish DCR and a controller must later persist a separate active
  * Consent before the study-scoped SMART request can succeed.
  *
- * Native R5 fields retain the exact study boundary in
- * `Consent.provision.data.reference` and the affected `ResearchSubject`
- * resource family. Project authorization actions remain create/read/update/
- * search; their FHIR representation uses the matching REST interaction codes,
- * where search is `search-type`. Delete is deliberately absent.
+ * The flat Consent claims retain the exact study boundary and affected
+ * `ResearchSubject` resource family. Delete is deliberately absent. Native
+ * FHIR projection belongs only at an explicit import/export boundary.
  *
  * @see https://hl7.org/fhir/R5/communication.html
  * @see https://hl7.org/fhir/R5/consent.html
@@ -177,64 +214,46 @@ export function buildVeterinaryResearchStudyPartyInvitation(input) {
     const consent = {
         resourceType: 'Consent',
         id: consentId,
-        status: 'draft',
-        grantor: [{ reference: controllerReference, type: 'Organization' }],
-        controller: [{ reference: controllerReference, type: 'Organization' }],
-        grantee: [{ reference: partyReference, type: 'PractitionerRole' }],
-        decision: 'permit',
-        provision: [{
-                actor: [{ reference: { reference: partyReference, type: 'PractitionerRole' } }],
-                action: VeterinaryResearchStudyPermissionActions.map(action => ({
-                    coding: [{
-                            system: FHIR_RESTFUL_INTERACTION_SYSTEM,
-                            code: action === 'search' ? 'search-type' : action,
-                        }],
-                })),
-                purpose: [{ system: topic.system, code: topic.code }],
-                resourceType: [{ system: FHIR_RESOURCE_TYPES_SYSTEM, code: 'ResearchSubject' }],
-                data: [{ meaning: 'related', reference: { reference: researchStudyReference, type: 'ResearchStudy' } }],
-            }],
         meta: {
             claims: {
-                [VeterinaryResearchStudyInvitationClaimNames.Context]: 'org.hl7.fhir.api',
-                [VeterinaryResearchStudyInvitationClaimNames.Status]: 'draft',
-                [VeterinaryResearchStudyInvitationClaimNames.Decision]: 'permit',
+                [VeterinaryResearchStudyInvitationClaimNames.Context]: InteroperableContext.FhirApi,
+                [VeterinaryResearchStudyInvitationClaimNames.Status]: ConsentStatuses.Draft,
+                [VeterinaryResearchStudyInvitationClaimNames.Decision]: ConsentDecisions.Permit,
                 [VeterinaryResearchStudyInvitationClaimNames.ActorIdentifier]: partyReference,
+                [ClaimConsent.grantee]: partyReference,
                 [VeterinaryResearchStudyInvitationClaimNames.Purpose]: topic.value,
                 [VeterinaryResearchStudyInvitationClaimNames.Action]: VeterinaryResearchStudyPermissionActions.join(','),
                 [VeterinaryResearchStudyInvitationClaimNames.ResourceType]: 'ResearchSubject',
+                [ClaimConsent.sourceReference]: researchStudyReference,
             },
         },
     };
-    const bundle = {
-        resourceType: 'Bundle',
-        type: 'batch',
-        entry: [{
-                fullUrl: `urn:uuid:${consentId}`,
+    const document = {
+        data: [{
+                type: 'Consent-v5.0.0',
                 resource: consent,
                 request: { method: 'POST', url: 'Consent' },
             }],
     };
     const category = VeterinaryCommunicationPresetFilters.ResearchAgreements.categories[0];
-    const [categorySystem, categoryCode] = splitCodingToken(category);
     const sent = optionalInstant(input.sentAt);
     return deepFreeze({
         resourceType: 'Communication',
         id: communicationId,
-        status: 'completed',
-        category: [{ coding: [{ system: categorySystem, code: categoryCode }] }],
-        topic: { coding: [{ system: topic.system, code: topic.code }] },
-        about: [{ reference: researchStudyReference, type: 'ResearchStudy' }],
-        recipient: [{ reference: partyReference, type: 'PractitionerRole' }],
-        sender: { reference: controllerReference, type: 'Organization' },
-        ...(sent ? { sent } : {}),
-        payload: [{
-                contentAttachment: {
-                    contentType: 'application/fhir+json',
-                    title: 'research-study-draft-consent.json',
-                    data: encodeJsonBase64(bundle),
-                },
-            }],
+        meta: { claims: {
+                '@context': InteroperableContext.FhirApi,
+                [CommunicationClaim.Identifier]: communicationId,
+                [CommunicationClaim.Status]: 'completed',
+                [CommunicationClaim.Category]: category,
+                [CommunicationClaim.Topic]: topic.value,
+                [CommunicationClaim.ContentReference]: researchStudyReference,
+                [CommunicationClaim.Recipient]: partyReference,
+                [CommunicationClaim.Sender]: controllerReference,
+                ...(sent ? { [CommunicationClaim.Sent]: sent } : {}),
+                [CommunicationClaim.ContentAttachmentType]: HttpMediaTypes.JsonApi,
+                [CommunicationClaim.ContentAttachmentTitle]: 'research-study-draft-consent.json',
+                [CommunicationClaim.ContentAttachmentData]: encodeJsonBase64(document),
+            } },
     });
 }
 /**
@@ -253,41 +272,77 @@ export function buildVeterinaryResearchStudyPartyInvitations(input) {
         ...invitation,
     })));
 }
-/** Decodes the single attached Consent Bundle after validating its boundary. */
-export function decodeVeterinaryResearchStudyInvitationBundle(communication) {
-    const attachment = communication?.payload?.[0]?.contentAttachment;
-    if (communication?.resourceType !== 'Communication'
-        || attachment?.contentType !== 'application/fhir+json'
-        || !attachment.data) {
-        throw new TypeError('veterinary_research_study_invitation_bundle_invalid');
+/** Decodes the attached JSON:API Consent document after validating its claims-only boundary. */
+export function decodeVeterinaryResearchStudyInvitationDocument(communication) {
+    if (!isClaimsOnlyResource(communication, 'Communication')) {
+        throw new TypeError('veterinary_research_study_invitation_document_invalid');
+    }
+    const claims = communication.meta.claims;
+    const encoded = claims[CommunicationClaim.ContentAttachmentData];
+    if (claims[CommunicationClaim.ContentAttachmentType] !== HttpMediaTypes.JsonApi || !encoded) {
+        throw new TypeError('veterinary_research_study_invitation_document_invalid');
     }
-    const decoded = JSON.parse(decodeJsonBase64(attachment.data));
-    if (decoded?.resourceType !== 'Bundle'
-        || decoded.type !== 'batch'
-        || decoded.entry?.length !== 1
-        || decoded.entry[0]?.resource?.resourceType !== 'Consent'
-        || decoded.entry[0].resource.status !== 'draft') {
-        throw new TypeError('veterinary_research_study_invitation_bundle_invalid');
+    let decoded;
+    try {
+        decoded = JSON.parse(decodeJsonBase64(encoded));
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_invitation_document_invalid');
+    }
+    const entry = decoded?.data?.[0];
+    if (decoded?.data?.length !== 1
+        || entry?.type !== 'Consent-v5.0.0'
+        || entry.request?.method !== 'POST'
+        || entry.request.url !== 'Consent'
+        || !isClaimsOnlyResource(entry.resource, 'Consent')
+        || entry.resource.meta.claims[ClaimConsent.status] !== ConsentStatuses.Draft) {
+        throw new TypeError('veterinary_research_study_invitation_document_invalid');
     }
     return deepFreeze(decoded);
 }
 function normalizedStudy(input) {
     if (!input || input.resourceType !== 'ResearchStudy')
         throw new TypeError('veterinary_research_study_invalid');
+    if (input.associatedParty !== undefined) {
+        throw new TypeError('veterinary_research_study_parties_require_patch_entries');
+    }
     const source = clonePlain(input);
     const id = boundedId(input.id);
     const status = String(input.status || '');
     if (!['draft', 'active', 'retired', 'unknown'].includes(status)) {
         throw new TypeError('veterinary_research_study_status_invalid');
     }
-    const associatedParty = input.associatedParty === undefined
-        ? undefined
-        : normalizeResearchStudyAssociatedParties(input.associatedParty);
     return deepFreeze({
         ...source,
         id,
         status: status,
-        ...(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');
+    }
+    let resource;
+    try {
+        resource = normalizeGroupR5FlatClaimsResource(input.resource);
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_group_entry_invalid');
+    }
+    const method = input.request?.method;
+    const expectedUrl = method === 'POST' ? 'Group' : method === 'PATCH' ? `Group/${resource.id}` : '';
+    if (!expectedUrl || input.request.url !== expectedUrl) {
+        throw new TypeError('veterinary_research_study_group_request_invalid');
+    }
+    return deepFreeze({
+        type: 'Group-v5.0.0',
+        resource,
+        request: { method, url: expectedUrl },
     });
 }
 function clonePlain(value) {
@@ -298,33 +353,44 @@ function clonePlain(value) {
     }
     return value;
 }
-function withProjectedClaims(study) {
-    const standardClaims = projectResearchStudyR5SearchClaims(study);
-    const partyClaims = aggregatePartyClaims(study.associatedParty || []);
+function normalizeResearchStudyBatchEntry(input) {
+    if (!input || input.type !== 'ResearchStudy-v5.0.0') {
+        throw new TypeError('veterinary_research_study_entry_invalid');
+    }
+    let resource;
+    try {
+        resource = normalizeResearchStudyR5FlatClaimsResource(input.resource);
+    }
+    catch {
+        throw new TypeError('veterinary_research_study_entry_invalid');
+    }
+    const method = input.request?.method;
+    const expectedUrl = method === 'POST'
+        ? 'ResearchStudy'
+        : method === 'PATCH'
+            ? `ResearchStudy/${resource.id}`
+            : '';
+    if (!expectedUrl || input.request.url !== expectedUrl) {
+        throw new TypeError('veterinary_research_study_request_invalid');
+    }
     return deepFreeze({
-        ...study,
-        meta: {
-            ...(study.meta || {}),
-            claims: { ...standardClaims, ...partyClaims },
-        },
+        type: 'ResearchStudy-v5.0.0',
+        resource,
+        request: { method, url: expectedUrl },
     });
 }
-function aggregatePartyClaims(parties) {
-    const output = {};
-    for (const projection of projectResearchStudyAssociatedPartyClaims(parties)) {
-        for (const [name, values] of Object.entries(projection.claims)) {
-            if (values.length > 0)
-                (output[name] || (output[name] = [])).push(...values);
-        }
-    }
-    return Object.fromEntries(Object.entries(output).map(([name, values]) => [name, Object.freeze([...values])]));
-}
 function boundedId(value) {
     const id = String(value || '').trim();
     if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
         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}/`;
@@ -352,13 +418,6 @@ function optionalInstant(value) {
         throw new TypeError('veterinary_research_study_invitation_sent_invalid');
     return instant;
 }
-function splitCodingToken(value) {
-    const separator = value.lastIndexOf('|');
-    if (separator < 1 || separator === value.length - 1) {
-        throw new TypeError('veterinary_research_study_invitation_category_invalid');
-    }
-    return [value.slice(0, separator), value.slice(separator + 1)];
-}
 function encodeJsonBase64(value) {
     const bytes = new TextEncoder().encode(JSON.stringify(value));
     let binary = '';
@@ -379,3 +438,15 @@ function deepFreeze(value, seen = new WeakSet()) {
         deepFreeze(nested, seen);
     return Object.freeze(value);
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isClaimsOnlyResource(value, resourceType) {
+    if (!isRecord(value) || value.resourceType !== resourceType)
+        return false;
+    if (Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
+        return false;
+    if (typeof value.id !== 'string' || !isRecord(value.meta) || !isRecord(value.meta.claims))
+        return false;
+    return Object.values(value.meta.claims).every(claim => typeof claim === 'string' && claim.trim().length > 0);
+}

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

@@ -4,8 +4,9 @@ This SDK separates study membership, an invitation, and authorization. They
 are three different facts:
 
 1. `ResearchStudy.associatedParty` records who is expected to collaborate.
-2. One R5 `Communication` invites that exact `PractitionerRole` and carries a
-   batch Bundle with one `Consent.status = draft`.
+2. One claims-only `Communication` invites that exact `PractitionerRole` and
+   carries a JSON:API primary document with one claims-only
+   `Consent.status = draft`.
 3. Only after the professional completes DCR and the controller persists a
    later `Consent.status = active` may the professional request the
    study-scoped SMART authorization.
@@ -17,10 +18,30 @@ related to the exact ResearchStudy. Whole-twin delete is absent.
 ```ts
 import {
   buildVeterinaryResearchStudyActiveConsentBatch,
+  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 invitations = buildVeterinaryResearchStudyPartyInvitations({
   researchStudyId: study.id,
   controllerReference: organizationReference,
@@ -60,23 +81,48 @@ const authorization = buildVeterinaryResearchStudySmartAuthorization({
 await professionalRuntime.requestSmartToken(authorization)
 ```
 
+The controller may independently create a descriptive review team with
+`buildVeterinaryResearchStudyGroupCreateEntry()` and append each registered
+`PractitionerRole` with
+`buildVeterinaryResearchStudyGroupMemberPatchEntries()`. Individual
+professionals are represented in the study by their separate
+`ResearchStudy.associatedParty` PATCH entries. The professional Group is not
+`ResearchStudy.recruitment.eligibility`: that FHIR element describes the
+research-subject cohort or its eligibility criteria. Group membership is not
+evidence of DCR or Consent and never grants the SMART authorization above.
+
+GW persistence entries for ResearchStudy, professional Group and active
+Consent contain only `resourceType`, `id` and `resource.meta.claims`. Their
+FHIR-like field names are flat claims. Native nested FHIR JSON is reserved for
+an explicit export/projection boundary, not these GW builders.
+
+The draft Consent inside the Communication attachment is an explicit
+`application/vnd.api+json` proposal for recipient review. Both the outer
+Communication and the attached Consent contain only `resourceType`, `id` and
+`resource.meta.claims`. It never authorizes access; only the later flat-claims
+active Consent POST is evaluated by GW.
+
+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:
+The JSON:API primary document is base64 encoded in canonical
+`Communication.content-attachment-data`, paired with
+`Communication.content-attachment-type = application/vnd.api+json`. The
+Consent claims use:
 
-- `Consent.grantee` and `Consent.provision.actor` for the invited
+- `Consent.grantee` and `Consent.actor-identifier` for the invited
   `PractitionerRole`;
-- `Consent.grantor` and `Consent.controller` for the controller organization;
-- `Consent.provision.purpose` with HL7 v3 ActReason `HRESCH`;
-- `Consent.provision.resourceType` for `ResearchSubject`;
-- `Consent.provision.data.reference` for the exact `ResearchStudy/{id}`;
-- FHIR REST interaction codes `create`, `read`, `update`, and `search-type`.
+- outer `Communication.sender` for the controller organization;
+- `Consent.purpose` with HL7 v3 ActReason `HRESCH`;
+- `Consent.resource-type` for `ResearchSubject`;
+- `Consent.source-reference` for the exact `ResearchStudy/{id}`;
+- `Consent.action` for `create`, `read`, `update`, and `search`.
 
 FHIR R5 references:
 

package/package.json

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