vet-data-utils-ts 0.5.26 → 0.5.28

package/README.md

@@ -119,6 +119,19 @@ cannot be attributed to the wrong party. A party classifier describes an
 organization category; it never represents Consent or CRUDS authorization. See
 [`docs/research-study-r5-contract.md`](docs/research-study-r5-contract.md).
 
+Explicit study provenance uses a separate claims-first FHIR R5 `Provenance`
+resource from `vet-data-utils-ts/provenance`. It exposes all thirteen
+resource-specific standard SearchParameters and preserves agent correlation as
+`Provenance.agent-<participation-type>-who`, where `<participation-type>` is an
+exact code from the FHIR ParticipationRoleType ValueSet and the value is the
+agent's FHIR Reference or URI. The standard `Provenance.agent` and
+`Provenance.agent-type` claims are indexed alongside that correlation claim.
+For a professional, use
+`buildPractitionerRoleReferenceFromAssignmentIdentifier()` with the real
+Occupation/PractitionerRole assignment UUID returned by GW. The role-bearing
+employee URN and role-license hash remain operational authorization identities;
+they are not substituted for the clinical `PractitionerRole` reference.
+
 ResearchStudy professional teams use native FHIR R5 Group resources from
 `vet-data-utils-ts/group`: required type and membership codes, the exact twelve
 resource-specific SearchParameters, canonical flat claim projection and
@@ -221,6 +234,8 @@ controls whether external catalogue searches may return it. Archiving that
 record withdraws discovery without deleting the study, eligibility/team
 Groups, ResearchSubjects or Dataset, and without changing `dct:accessRights`.
 No individual ResearchSubject identifier is projected into HealthDCAT.
+The Dataset `dct:provenance` points to the separate FHIR `Provenance` record;
+it does not replace the `prov:wasGeneratedBy` study relationship.
 `Distribution` describes the HDAB-controlled representation; `DataService`
 describes the host API serving Dataset metadata.
 

package/dist/health-dcat.d.ts

@@ -149,6 +149,7 @@ export declare function buildHealthDcatDataService(input: ControllerAuthority &
 export declare function buildResearchStudyDatasetPublication(input: ControllerAuthority & Readonly<{
     dataset: unknown;
     researchStudyIdentifier: string;
+    provenanceReference: string;
     catalogRecordIdentifier: string;
     status: HealthDcatCatalogRecordStatus;
     modifiedAt: string;

package/dist/health-dcat.js

@@ -303,12 +303,19 @@ export function buildResearchStudyDatasetPublication(input) {
     const researchStudyIdentifier = required(input.researchStudyIdentifier, 'researchStudyIdentifier');
     if (!researchStudyIdentifier.startsWith('ResearchStudy/'))
         throw new TypeError('research_study_reference_invalid');
+    const provenanceReference = required(input.provenanceReference, 'provenanceReference');
+    if (!provenanceReference.startsWith('Provenance/'))
+        throw new TypeError('provenance_reference_invalid');
     const modifiedAt = new Date(input.modifiedAt);
     if (!Number.isFinite(modifiedAt.getTime()) || modifiedAt.toISOString() !== input.modifiedAt)
         throw new TypeError('modifiedAt must be an ISO instant');
     const linkedDataset = normalizeHealthDcatResource({
         ...dataset,
-        meta: { claims: { ...dataset.meta.claims, [ClaimsHealthDcatDataset.wasGeneratedBy]: researchStudyIdentifier } },
+        meta: { claims: {
+                ...dataset.meta.claims,
+                [ClaimsHealthDcatDataset.wasGeneratedBy]: researchStudyIdentifier,
+                [ClaimsHealthDcatDataset.provenance]: provenanceReference,
+            } },
     });
     const recordId = required(input.catalogRecordIdentifier, 'catalogRecordIdentifier');
     const record = normalizeHealthDcatResource({

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './iso-jurisdictions.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';
 export * from './shc.js';

package/dist/provenance.d.ts

@@ -0,0 +1,42 @@
+export declare const FhirR5ParticipationRoleTypeValueSet: "http://hl7.org/fhir/ValueSet/participation-role-type";
+export declare const FhirR5ProvenanceParticipantTypeSystem: "http://terminology.hl7.org/CodeSystem/provenance-participant-type";
+export declare const FhirR5ExtraSecurityRoleTypeSystem: "http://terminology.hl7.org/CodeSystem/extra-security-role-type";
+export declare const DicomControlledTerminologySystem: "http://dicom.nema.org/resources/ontology/DCM";
+/** Exact FHIR R5 ParticipationRoleType 5.0.0 expansion used by Provenance.agent.type. */
+export declare const FhirR5ParticipationRoleTypeCodes: readonly ["enterer", "performer", "author", "verifier", "legal", "attester", "informant", "custodian", "assembler", "composer", "110150", "110151", "110152", "110153", "110154", "110155", "authserver", "datacollector", "dataprocessor", "datasubject", "humanuser"];
+export type FhirR5ParticipationRoleTypeCode = (typeof FhirR5ParticipationRoleTypeCodes)[number];
+export type ProvenanceSearchParameterType = 'date' | 'reference' | 'token';
+export type ProvenanceR5SearchParameter = Readonly<{
+    code: string;
+    type: ProvenanceSearchParameterType;
+    expression: string;
+}>;
+/** Exact resource-specific FHIR R5 Provenance SearchParameters. */
+export declare const ProvenanceR5SearchParameterCatalog: readonly ProvenanceR5SearchParameter[];
+/** Standard search claims plus typed-agent correlation claims. */
+export declare const ProvenanceFlatClaimCatalog: readonly string[];
+export type ProvenanceR5FlatClaimsResource = Readonly<{
+    resourceType: 'Provenance';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, readonly string[]>>;
+    }>;
+}>;
+/** Builds the FHIR PractitionerRole reference from the server-issued assignment UUID. */
+export declare function buildPractitionerRoleReferenceFromAssignmentIdentifier(assignmentIdentifier: string): string;
+/** Returns the correlated agent reference claim for one official participation type. */
+export declare function provenanceAgentClaim(code: FhirR5ParticipationRoleTypeCode | string): string;
+/** Returns the system-qualified FHIR token for one official participation type. */
+export declare function participationRoleTypeToken(code: FhirR5ParticipationRoleTypeCode): string;
+/** Validates a claims-only Provenance resource and rejects nested/native fields. */
+export declare function normalizeProvenanceR5FlatClaimsResource(candidate: unknown): ProvenanceR5FlatClaimsResource;
+/** Builds provenance for creation or update of a ResearchStudy with correlated typed agents. */
+export declare function buildResearchStudyProvenanceResource(input: Readonly<{
+    id: string;
+    researchStudyReference: string;
+    recorded: string;
+    agents: readonly Readonly<{
+        type: FhirR5ParticipationRoleTypeCode;
+        who: string;
+    }>[];
+}>): ProvenanceR5FlatClaimsResource;

package/dist/provenance.js

@@ -0,0 +1,108 @@
+/** Browser-safe FHIR R5 Provenance flat-claim vocabulary and builders. */
+import { normalizeUuid } from 'gdc-common-utils-ts/utils/normalize-uuid';
+export const FhirR5ParticipationRoleTypeValueSet = 'http://hl7.org/fhir/ValueSet/participation-role-type';
+export const FhirR5ProvenanceParticipantTypeSystem = 'http://terminology.hl7.org/CodeSystem/provenance-participant-type';
+export const FhirR5ExtraSecurityRoleTypeSystem = 'http://terminology.hl7.org/CodeSystem/extra-security-role-type';
+export const DicomControlledTerminologySystem = 'http://dicom.nema.org/resources/ontology/DCM';
+/** Exact FHIR R5 ParticipationRoleType 5.0.0 expansion used by Provenance.agent.type. */
+export const FhirR5ParticipationRoleTypeCodes = Object.freeze([
+    'enterer', 'performer', 'author', 'verifier', 'legal', 'attester', 'informant',
+    'custodian', 'assembler', 'composer', '110150', '110151', '110152', '110153',
+    '110154', '110155', 'authserver', 'datacollector', 'dataprocessor', 'datasubject',
+    'humanuser',
+]);
+/** Exact resource-specific FHIR R5 Provenance SearchParameters. */
+export const ProvenanceR5SearchParameterCatalog = Object.freeze([
+    { code: 'activity', type: 'token', expression: 'Provenance.activity' },
+    { code: 'agent', type: 'reference', expression: 'Provenance.agent.who' },
+    { code: 'agent-role', type: 'token', expression: 'Provenance.agent.role' },
+    { code: 'agent-type', type: 'token', expression: 'Provenance.agent.type' },
+    { code: 'based-on', type: 'reference', expression: 'Provenance.basedOn' },
+    { code: 'encounter', type: 'reference', expression: 'Provenance.encounter' },
+    { code: 'entity', type: 'reference', expression: 'Provenance.entity.what' },
+    { code: 'location', type: 'reference', expression: 'Provenance.location' },
+    { code: 'patient', type: 'reference', expression: 'Provenance.patient' },
+    { code: 'recorded', type: 'date', expression: 'Provenance.recorded' },
+    { code: 'signature-type', type: 'token', expression: 'Provenance.signature.type' },
+    { code: 'target', type: 'reference', expression: 'Provenance.target' },
+    { code: 'when', type: 'date', expression: 'Provenance.occurred.ofType(dateTime)' },
+]);
+const standardClaims = ProvenanceR5SearchParameterCatalog.map(parameter => `Provenance.${parameter.code}`);
+const correlatedAgentClaims = FhirR5ParticipationRoleTypeCodes.map(code => `Provenance.agent-${code}-who`);
+/** Standard search claims plus typed-agent correlation claims. */
+export const ProvenanceFlatClaimCatalog = Object.freeze([...standardClaims, ...correlatedAgentClaims]);
+/** Builds the FHIR PractitionerRole reference from the server-issued assignment UUID. */
+export function buildPractitionerRoleReferenceFromAssignmentIdentifier(assignmentIdentifier) {
+    const compact = normalizeUuid(assignmentIdentifier);
+    if (!compact)
+        throw new TypeError('professional_assignment_identifier_invalid');
+    const uuid = `${compact.slice(0, 8)}-${compact.slice(8, 12)}-${compact.slice(12, 16)}-${compact.slice(16, 20)}-${compact.slice(20)}`;
+    return `PractitionerRole/${uuid}`;
+}
+/** Returns the correlated agent reference claim for one official participation type. */
+export function provenanceAgentClaim(code) {
+    if (!FhirR5ParticipationRoleTypeCodes.includes(code))
+        throw new TypeError('participation_role_type_invalid');
+    return `Provenance.agent-${code}-who`;
+}
+/** Returns the system-qualified FHIR token for one official participation type. */
+export function participationRoleTypeToken(code) {
+    const system = /^11015[0-5]$/.test(code)
+        ? DicomControlledTerminologySystem
+        : ['authserver', 'datacollector', 'dataprocessor', 'datasubject', 'humanuser'].includes(code)
+            ? FhirR5ExtraSecurityRoleTypeSystem
+            : FhirR5ProvenanceParticipantTypeSystem;
+    return `${system}|${code}`;
+}
+/** Validates a claims-only Provenance resource and rejects nested/native fields. */
+export function normalizeProvenanceR5FlatClaimsResource(candidate) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+        throw new TypeError('provenance_flat_resource_invalid');
+    const input = candidate;
+    if (input.resourceType !== 'Provenance' || typeof input.id !== 'string' || !input.id.trim())
+        throw new TypeError('provenance_flat_resource_invalid');
+    if (Object.keys(input).some(key => !['resourceType', 'id', 'meta'].includes(key)))
+        throw new TypeError('provenance_flat_resource_invalid');
+    const meta = input.meta;
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta) || Object.keys(meta).some(key => key !== 'claims'))
+        throw new TypeError('provenance_flat_resource_invalid');
+    const claims = meta.claims;
+    if (!claims || typeof claims !== 'object' || Array.isArray(claims))
+        throw new TypeError('provenance_flat_resource_invalid');
+    const normalized = {};
+    for (const [name, rawValue] of Object.entries(claims)) {
+        if (!ProvenanceFlatClaimCatalog.includes(name))
+            throw new TypeError('provenance_flat_claim_invalid');
+        const values = (Array.isArray(rawValue) ? rawValue : [rawValue]).map(value => String(value).trim()).filter(Boolean);
+        if (!values.length)
+            throw new TypeError('provenance_flat_claim_value_invalid');
+        normalized[name] = Object.freeze(values);
+    }
+    return Object.freeze({ resourceType: 'Provenance', id: input.id.trim(), meta: Object.freeze({ claims: Object.freeze(normalized) }) });
+}
+/** Builds provenance for creation or update of a ResearchStudy with correlated typed agents. */
+export function buildResearchStudyProvenanceResource(input) {
+    if (!input.researchStudyReference.startsWith('ResearchStudy/'))
+        throw new TypeError('research_study_reference_invalid');
+    const recorded = new Date(input.recorded);
+    if (!Number.isFinite(recorded.getTime()) || recorded.toISOString() !== input.recorded)
+        throw new TypeError('recorded_instant_invalid');
+    if (!input.agents.length)
+        throw new TypeError('provenance_agent_required');
+    const claims = {
+        'Provenance.target': [input.researchStudyReference],
+        'Provenance.recorded': [input.recorded],
+        'Provenance.agent': [],
+        'Provenance.agent-type': [],
+    };
+    for (const agent of input.agents) {
+        const who = String(agent.who || '').trim();
+        if (!who)
+            throw new TypeError('provenance_agent_who_required');
+        claims['Provenance.agent'].push(who);
+        claims['Provenance.agent-type'].push(participationRoleTypeToken(agent.type));
+        const correlatedClaim = provenanceAgentClaim(agent.type);
+        (claims[correlatedClaim] ||= []).push(who);
+    }
+    return normalizeProvenanceR5FlatClaimsResource({ resourceType: 'Provenance', id: input.id, meta: { claims } });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.26",
+  "version": "0.5.28",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -72,6 +72,10 @@
       "types": "./dist/payment.d.ts",
       "default": "./dist/payment.js"
     },
+    "./provenance": {
+      "types": "./dist/provenance.d.ts",
+      "default": "./dist/provenance.js"
+    },
     "./place-service-directory": {
       "types": "./dist/place-service-directory.d.ts",
       "default": "./dist/place-service-directory.js"