vet-data-utils-ts 0.5.25 → 0.5.27

package/README.md

@@ -119,6 +119,14 @@ 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.
+
 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
@@ -215,6 +223,17 @@ authorization are separate checks performed by their owning adapters.
 `projectHealthDcatResourceToJsonLd()` is the explicit standards serialization
 boundary used by host/dataspace adapters.
 
+Research publication is study-scoped. A derived cohort Dataset links to its
+generating `ResearchStudy` through PROV-O and a separate `CatalogRecord`
+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.
+
 `vet-data-utils-ts/organization-application` is the product-neutral application
 value used by UHC UNID, VetChain and SOSChain adapters. The host supplies the
 allowed sector list and translated labels. The value contains one official

package/dist/health-dcat.d.ts

@@ -19,6 +19,7 @@ export declare enum ClaimsHealthDcatDataset {
     distribution = "dcat.distribution",
     source = "dct.source",
     provenance = "dct.provenance",
+    wasGeneratedBy = "prov.wasGeneratedBy",
     personalData = "dpv.hasPersonalData",
     healthCategory = "healthdcatap.healthCategory",
     healthDataAccessBody = "healthdcatap.hdab",
@@ -38,13 +39,47 @@ export declare enum ClaimsHealthDcatCatalog {
     dataset = "dcat.dataset",
     userSelected = "Catalog.user-selected"
 }
+/** DCAT Catalogue Record editorial claims; status is distinct from data access rights. */
+export declare enum ClaimsHealthDcatCatalogRecord {
+    identifier = "dct.identifier",
+    primaryTopic = "foaf.primaryTopic",
+    status = "adms.status",
+    modified = "dct.modified",
+    conformsTo = "dct.conformsTo",
+    userSelected = "CatalogRecord.user-selected"
+}
+/** DCAT Distribution claims used for downloadable or controlled-access representations. */
+export declare enum ClaimsHealthDcatDistribution {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    accessUrl = "dcat.accessURL",
+    format = "dct.format",
+    mediaType = "dcat.mediaType",
+    accessRights = "dct.accessRights",
+    policy = "odrl.hasPolicy",
+    userSelected = "Distribution.user-selected"
+}
+/** DCAT DataService claims used for host APIs serving one or more Datasets. */
+export declare enum ClaimsHealthDcatDataService {
+    identifier = "dct.identifier",
+    title = "dct.title",
+    publisher = "dct.publisher",
+    endpointUrl = "dcat.endpointURL",
+    servesDataset = "dcat.servesDataset",
+    accessRights = "dct.accessRights",
+    userSelected = "DataService.user-selected"
+}
+export type HealthDcatCatalogRecordStatus = 'draft' | 'published' | 'archived';
 /** Complete allowlist for product-persisted HealthDCAT flat claims. */
 export declare const HealthDcatFlatClaimCatalog: Readonly<{
     readonly Dataset: readonly ClaimsHealthDcatDataset[];
     readonly Catalog: readonly ClaimsHealthDcatCatalog[];
+    readonly CatalogRecord: readonly ClaimsHealthDcatCatalogRecord[];
+    readonly Distribution: readonly ClaimsHealthDcatDistribution[];
+    readonly DataService: readonly ClaimsHealthDcatDataService[];
 }>;
 export type HealthDcatResource = Readonly<{
-    resourceType: 'Dataset' | 'Catalog';
+    resourceType: 'Dataset' | 'Catalog' | 'CatalogRecord' | 'Distribution' | 'DataService';
     id: string;
     meta: Readonly<{
         claims: Readonly<Record<string, ClaimValue>>;
@@ -87,6 +122,49 @@ export declare function buildHealthDcatCatalog(input: ControllerAuthority & Read
     datasetIdentifiers: readonly string[];
     applicableLegislation: readonly string[];
 }>): HealthDcatResource;
+/** Builds a governed Dataset Distribution without exposing the source records. */
+export declare function buildHealthDcatDistribution(input: ControllerAuthority & Readonly<{
+    id: string;
+    title: string;
+    accessUrl: string;
+    format: string;
+    mediaType?: string;
+    accessRights: HealthDcatAccessRights;
+    healthDataAccessBodyIdentifier: string;
+    policyIdentifier?: string;
+}>): HealthDcatResource;
+/** Builds metadata for a host API that serves published Dataset descriptions. */
+export declare function buildHealthDcatDataService(input: ControllerAuthority & Readonly<{
+    id: string;
+    title: string;
+    endpointUrl: string;
+    servesDatasetIdentifiers: readonly string[];
+    accessRights: HealthDcatAccessRights;
+}>): HealthDcatResource;
+/**
+ * Links one cohort Dataset to the ResearchStudy that generated it and creates
+ * the separate editorial CatalogRecord controlling external discoverability.
+ * ResearchSubject identifiers are deliberately absent from this projection.
+ */
+export declare function buildResearchStudyDatasetPublication(input: ControllerAuthority & Readonly<{
+    dataset: unknown;
+    researchStudyIdentifier: string;
+    provenanceReference: string;
+    catalogRecordIdentifier: string;
+    status: HealthDcatCatalogRecordStatus;
+    modifiedAt: string;
+}>): Readonly<{
+    dataset: HealthDcatResource;
+    record: HealthDcatResource;
+}>;
+/** Controller-only editorial transition; archiving removes external discovery only. */
+export declare function updateHealthDcatCatalogRecordStatus(input: ControllerAuthority & Readonly<{
+    record: unknown;
+    status: HealthDcatCatalogRecordStatus;
+    modifiedAt: string;
+}>): HealthDcatResource;
+/** True only for records eligible for an external marketplace search result. */
+export declare function isHealthDcatCatalogRecordExternallyDiscoverable(record: unknown): boolean;
 /** Creates an auditable tenant authorization for host-provided catalogue federation. */
 export declare function buildHealthDcatFederationRequest(input: ControllerAuthority & Readonly<{
     catalogIdentifier: string;

package/dist/health-dcat.js

@@ -21,6 +21,7 @@ export var ClaimsHealthDcatDataset;
     ClaimsHealthDcatDataset["distribution"] = "dcat.distribution";
     ClaimsHealthDcatDataset["source"] = "dct.source";
     ClaimsHealthDcatDataset["provenance"] = "dct.provenance";
+    ClaimsHealthDcatDataset["wasGeneratedBy"] = "prov.wasGeneratedBy";
     ClaimsHealthDcatDataset["personalData"] = "dpv.hasPersonalData";
     ClaimsHealthDcatDataset["healthCategory"] = "healthdcatap.healthCategory";
     ClaimsHealthDcatDataset["healthDataAccessBody"] = "healthdcatap.hdab";
@@ -41,17 +42,53 @@ export var ClaimsHealthDcatCatalog;
     ClaimsHealthDcatCatalog["dataset"] = "dcat.dataset";
     ClaimsHealthDcatCatalog["userSelected"] = "Catalog.user-selected";
 })(ClaimsHealthDcatCatalog || (ClaimsHealthDcatCatalog = {}));
+/** DCAT Catalogue Record editorial claims; status is distinct from data access rights. */
+export var ClaimsHealthDcatCatalogRecord;
+(function (ClaimsHealthDcatCatalogRecord) {
+    ClaimsHealthDcatCatalogRecord["identifier"] = "dct.identifier";
+    ClaimsHealthDcatCatalogRecord["primaryTopic"] = "foaf.primaryTopic";
+    ClaimsHealthDcatCatalogRecord["status"] = "adms.status";
+    ClaimsHealthDcatCatalogRecord["modified"] = "dct.modified";
+    ClaimsHealthDcatCatalogRecord["conformsTo"] = "dct.conformsTo";
+    ClaimsHealthDcatCatalogRecord["userSelected"] = "CatalogRecord.user-selected";
+})(ClaimsHealthDcatCatalogRecord || (ClaimsHealthDcatCatalogRecord = {}));
+/** DCAT Distribution claims used for downloadable or controlled-access representations. */
+export var ClaimsHealthDcatDistribution;
+(function (ClaimsHealthDcatDistribution) {
+    ClaimsHealthDcatDistribution["identifier"] = "dct.identifier";
+    ClaimsHealthDcatDistribution["title"] = "dct.title";
+    ClaimsHealthDcatDistribution["accessUrl"] = "dcat.accessURL";
+    ClaimsHealthDcatDistribution["format"] = "dct.format";
+    ClaimsHealthDcatDistribution["mediaType"] = "dcat.mediaType";
+    ClaimsHealthDcatDistribution["accessRights"] = "dct.accessRights";
+    ClaimsHealthDcatDistribution["policy"] = "odrl.hasPolicy";
+    ClaimsHealthDcatDistribution["userSelected"] = "Distribution.user-selected";
+})(ClaimsHealthDcatDistribution || (ClaimsHealthDcatDistribution = {}));
+/** DCAT DataService claims used for host APIs serving one or more Datasets. */
+export var ClaimsHealthDcatDataService;
+(function (ClaimsHealthDcatDataService) {
+    ClaimsHealthDcatDataService["identifier"] = "dct.identifier";
+    ClaimsHealthDcatDataService["title"] = "dct.title";
+    ClaimsHealthDcatDataService["publisher"] = "dct.publisher";
+    ClaimsHealthDcatDataService["endpointUrl"] = "dcat.endpointURL";
+    ClaimsHealthDcatDataService["servesDataset"] = "dcat.servesDataset";
+    ClaimsHealthDcatDataService["accessRights"] = "dct.accessRights";
+    ClaimsHealthDcatDataService["userSelected"] = "DataService.user-selected";
+})(ClaimsHealthDcatDataService || (ClaimsHealthDcatDataService = {}));
 /** Complete allowlist for product-persisted HealthDCAT flat claims. */
 export const HealthDcatFlatClaimCatalog = Object.freeze({
     Dataset: Object.freeze(Object.values(ClaimsHealthDcatDataset)),
     Catalog: Object.freeze(Object.values(ClaimsHealthDcatCatalog)),
+    CatalogRecord: Object.freeze(Object.values(ClaimsHealthDcatCatalogRecord)),
+    Distribution: Object.freeze(Object.values(ClaimsHealthDcatDistribution)),
+    DataService: Object.freeze(Object.values(ClaimsHealthDcatDataService)),
 });
 /** Validates an indexed HealthDCAT resource and rejects nested or unknown claims. */
 export function normalizeHealthDcatResource(candidate) {
     if (!candidate || typeof candidate !== 'object')
         throw new TypeError('health_dcat_resource_invalid');
     const value = candidate;
-    if (value.resourceType !== 'Dataset' && value.resourceType !== 'Catalog')
+    if (!['Dataset', 'Catalog', 'CatalogRecord', 'Distribution', 'DataService'].includes(String(value.resourceType)))
         throw new TypeError('health_dcat_resource_invalid');
     if (typeof value.id !== 'string' || !value.id.trim())
         throw new TypeError('health_dcat_resource_invalid');
@@ -60,7 +97,8 @@ export function normalizeHealthDcatResource(candidate) {
     const claims = value.meta.claims;
     if (!claims || typeof claims !== 'object' || Array.isArray(claims))
         throw new TypeError('health_dcat_resource_invalid');
-    const allowed = HealthDcatFlatClaimCatalog[value.resourceType];
+    const resourceType = value.resourceType;
+    const allowed = HealthDcatFlatClaimCatalog[resourceType];
     const normalized = {};
     for (const [claim, raw] of Object.entries(claims)) {
         if (!allowed.includes(claim))
@@ -73,7 +111,7 @@ export function normalizeHealthDcatResource(candidate) {
             throw new TypeError(`health_dcat_claim_value_invalid:${claim}`);
     }
     return Object.freeze({
-        resourceType: value.resourceType,
+        resourceType,
         id: value.id,
         meta: Object.freeze({ claims: Object.freeze(normalized) }),
     });
@@ -90,6 +128,7 @@ const JsonLdClaimNames = Object.freeze({
     [ClaimsHealthDcatDataset.distribution]: 'dcat:distribution',
     [ClaimsHealthDcatDataset.source]: 'dct:source',
     [ClaimsHealthDcatDataset.provenance]: 'dct:provenance',
+    [ClaimsHealthDcatDataset.wasGeneratedBy]: 'prov:wasGeneratedBy',
     [ClaimsHealthDcatDataset.personalData]: 'dpv:hasPersonalData',
     [ClaimsHealthDcatDataset.healthCategory]: 'healthdcatap:healthCategory',
     [ClaimsHealthDcatDataset.healthDataAccessBody]: 'healthdcatap:hdab',
@@ -97,6 +136,16 @@ const JsonLdClaimNames = Object.freeze({
     [ClaimsHealthDcatDataset.variables]: 'healthdcatap:hasVariables',
     [ClaimsHealthDcatDataset.authorizationReference]: 'prov:qualifiedAttribution',
     [ClaimsHealthDcatCatalog.dataset]: 'dcat:dataset',
+    [ClaimsHealthDcatCatalogRecord.primaryTopic]: 'foaf:primaryTopic',
+    [ClaimsHealthDcatCatalogRecord.status]: 'adms:status',
+    [ClaimsHealthDcatCatalogRecord.modified]: 'dct:modified',
+    [ClaimsHealthDcatCatalogRecord.conformsTo]: 'dct:conformsTo',
+    [ClaimsHealthDcatDistribution.accessUrl]: 'dcat:accessURL',
+    [ClaimsHealthDcatDistribution.format]: 'dct:format',
+    [ClaimsHealthDcatDistribution.mediaType]: 'dcat:mediaType',
+    [ClaimsHealthDcatDistribution.policy]: 'odrl:hasPolicy',
+    [ClaimsHealthDcatDataService.endpointUrl]: 'dcat:endpointURL',
+    [ClaimsHealthDcatDataService.servesDataset]: 'dcat:servesDataset',
 });
 /** Explicitly projects internal flat claims to DCAT/HealthDCAT JSON-LD. */
 export function projectHealthDcatResourceToJsonLd(resource) {
@@ -110,9 +159,12 @@ export function projectHealthDcatResourceToJsonLd(resource) {
             healthdcatap: 'http://healthdataportal.eu/ns/health#',
             dpv: 'https://w3id.org/dpv#',
             prov: 'http://www.w3.org/ns/prov#',
+            foaf: 'http://xmlns.com/foaf/0.1/',
+            adms: 'http://www.w3.org/ns/adms#',
+            odrl: 'http://www.w3.org/ns/odrl/2/',
         }),
         '@id': normalized.id,
-        '@type': normalized.resourceType === 'Catalog' ? 'dcat:Catalog' : 'dcat:Dataset',
+        '@type': `dcat:${normalized.resourceType}`,
     };
     for (const [claim, value] of Object.entries(normalized.meta.claims)) {
         const jsonLdName = JsonLdClaimNames[claim];
@@ -197,6 +249,118 @@ export function buildHealthDcatCatalog(input) {
     };
     return Object.freeze({ resourceType: 'Catalog', id: input.id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
 }
+/** Builds a governed Dataset Distribution without exposing the source records. */
+export function buildHealthDcatDistribution(input) {
+    assertController(input);
+    required(input.healthDataAccessBodyIdentifier, 'healthDataAccessBodyIdentifier');
+    const accessUrl = required(input.accessUrl, 'accessUrl');
+    if (!accessUrl.startsWith('https://'))
+        throw new TypeError('accessUrl must use HTTPS');
+    const claims = {
+        [ClaimsHealthDcatDistribution.identifier]: required(input.id, 'id'),
+        [ClaimsHealthDcatDistribution.title]: required(input.title, 'title'),
+        [ClaimsHealthDcatDistribution.accessUrl]: accessUrl,
+        [ClaimsHealthDcatDistribution.format]: required(input.format, 'format'),
+        [ClaimsHealthDcatDistribution.accessRights]: input.accessRights,
+        [ClaimsHealthDcatDistribution.userSelected]: true,
+    };
+    if (input.mediaType)
+        claims[ClaimsHealthDcatDistribution.mediaType] = required(input.mediaType, 'mediaType');
+    if (input.policyIdentifier)
+        claims[ClaimsHealthDcatDistribution.policy] = required(input.policyIdentifier, 'policyIdentifier');
+    return normalizeHealthDcatResource({ resourceType: 'Distribution', id: input.id, meta: { claims } });
+}
+/** Builds metadata for a host API that serves published Dataset descriptions. */
+export function buildHealthDcatDataService(input) {
+    assertController(input);
+    const endpointUrl = required(input.endpointUrl, 'endpointUrl');
+    if (!endpointUrl.startsWith('https://'))
+        throw new TypeError('endpointUrl must use HTTPS');
+    if (!input.servesDatasetIdentifiers.length)
+        throw new TypeError('servesDatasetIdentifiers are required');
+    return normalizeHealthDcatResource({
+        resourceType: 'DataService', id: input.id, meta: { claims: {
+                [ClaimsHealthDcatDataService.identifier]: required(input.id, 'id'),
+                [ClaimsHealthDcatDataService.title]: required(input.title, 'title'),
+                [ClaimsHealthDcatDataService.publisher]: required(input.organizationIdentifier, 'organizationIdentifier'),
+                [ClaimsHealthDcatDataService.endpointUrl]: endpointUrl,
+                [ClaimsHealthDcatDataService.servesDataset]: Object.freeze([...input.servesDatasetIdentifiers]),
+                [ClaimsHealthDcatDataService.accessRights]: input.accessRights,
+                [ClaimsHealthDcatDataService.userSelected]: true,
+            } },
+    });
+}
+/**
+ * Links one cohort Dataset to the ResearchStudy that generated it and creates
+ * the separate editorial CatalogRecord controlling external discoverability.
+ * ResearchSubject identifiers are deliberately absent from this projection.
+ */
+export function buildResearchStudyDatasetPublication(input) {
+    assertController(input);
+    const dataset = normalizeHealthDcatResource(input.dataset);
+    if (dataset.resourceType !== 'Dataset')
+        throw new TypeError('research_dataset_required');
+    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,
+                [ClaimsHealthDcatDataset.provenance]: provenanceReference,
+            } },
+    });
+    const recordId = required(input.catalogRecordIdentifier, 'catalogRecordIdentifier');
+    const record = normalizeHealthDcatResource({
+        resourceType: 'CatalogRecord',
+        id: recordId,
+        meta: { claims: {
+                [ClaimsHealthDcatCatalogRecord.identifier]: recordId,
+                [ClaimsHealthDcatCatalogRecord.primaryTopic]: `Dataset/${dataset.id}`,
+                [ClaimsHealthDcatCatalogRecord.status]: input.status,
+                [ClaimsHealthDcatCatalogRecord.modified]: input.modifiedAt,
+                [ClaimsHealthDcatCatalogRecord.conformsTo]: 'HealthDCAT-AP Release 7',
+                [ClaimsHealthDcatCatalogRecord.userSelected]: true,
+            } },
+    });
+    return Object.freeze({ dataset: linkedDataset, record });
+}
+/** Controller-only editorial transition; archiving removes external discovery only. */
+export function updateHealthDcatCatalogRecordStatus(input) {
+    assertController(input);
+    const record = normalizeHealthDcatResource(input.record);
+    if (record.resourceType !== 'CatalogRecord')
+        throw new TypeError('health_dcat_catalog_record_required');
+    const timestamp = new Date(input.modifiedAt);
+    if (!Number.isFinite(timestamp.getTime()) || timestamp.toISOString() !== input.modifiedAt)
+        throw new TypeError('modifiedAt must be an ISO instant');
+    return normalizeHealthDcatResource({
+        ...record,
+        meta: { claims: {
+                ...record.meta.claims,
+                [ClaimsHealthDcatCatalogRecord.status]: input.status,
+                [ClaimsHealthDcatCatalogRecord.modified]: input.modifiedAt,
+            } },
+    });
+}
+/** True only for records eligible for an external marketplace search result. */
+export function isHealthDcatCatalogRecordExternallyDiscoverable(record) {
+    try {
+        const normalized = normalizeHealthDcatResource(record);
+        return normalized.resourceType === 'CatalogRecord'
+            && normalized.meta.claims[ClaimsHealthDcatCatalogRecord.status] === 'published';
+    }
+    catch {
+        return false;
+    }
+}
 /** Creates an auditable tenant authorization for host-provided catalogue federation. */
 export function buildHealthDcatFederationRequest(input) {
     assertController(input);

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,41 @@
+/** Browser-safe FHIR R5 Provenance flat-claim vocabulary and builders. */
+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[]>>;
+    }>;
+}>;
+/** 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,99 @@
+/** Browser-safe FHIR R5 Provenance flat-claim vocabulary and builders. */
+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]);
+/** 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.25",
+  "version": "0.5.27",
   "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"