vet-data-utils-ts 0.5.32 → 0.5.37

package/README.md

@@ -1,4 +1,13 @@
 # vet-data-utils-ts
+## Blocking local-first SDK release
+
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its
+indivisible order is **local packages -> full local test matrix -> merge every
+validated branch to `main` -> publish bottom-up -> install exact registry
+versions and commit lockfiles on `main` -> staging**. Never publish to discover
+deterministic failures and never commit a local package reference. Staging
+begins only after exact registry packages are installed and verified.
+
 
 ## Lost-animal access and behavior
 
@@ -189,6 +198,16 @@ for immunologicals); ordinary human ATC is not substituted for it. Veterinary
 allergy product coding may also use ATCvet, while manifestations use an allowed
 SNOMED source.
 
+Terminology-assisted entry uses the neutral coding-review contract from
+`fhir-data-utils-ts/coding-review-flat-claims`. Spoken, typed or imported text
+is `Immunization.vaccine-code-text`; an unconfirmed candidate stays in
+`meta.codingProposals[]` beside the Immunization's `meta.claims`, targets
+`Immunization.vaccine-code`, and is never copied to `ResearchSubject.meta`.
+Confirmation adds the selected `system|code` and official `-display` without
+overwriting local `-text`. Vet policy supplies ATCvet/species constraints; it
+does not redefine the shared shape. Consumers reuse exported fixtures and
+builders rather than repeating governed literals.
+
 `vet-data-utils-ts/veterinary-biologic-product` keeps three independent axes:
 
 - WHO ATCvet QI is the international medicine classification;
@@ -280,7 +299,8 @@ value used by UHC UNID, VetChain and SOSChain adapters. The host supplies the
 allowed sector list and translated labels. The value contains one official
 identifier (`TAX`, `EIN` or `BN`), ISO country, optional matching ISO
 subdivision, optional official licence, legal representative, technical
-controller and six independent index participation roles. It rejects a second
+controller and independent index, personal-backup and Digital Twin
+participation roles. It rejects a second
 `taxId` and every PIN field: profile protection happens immediately after
 login, before any application screen.
 

package/dist/clinical-bundle-reader.js

@@ -1,4 +1,5 @@
 import { normalizeClaimsFromFhirResource } from 'gdc-common-utils-ts/utils/interoperable-resource-operation';
+import { normalizeFhirApiClaimKey } from 'gdc-common-utils-ts/utils/fhir-api-claim-helpers';
 const PRIMARY_CODE_PROJECTIONS = Object.freeze({
     Condition: { field: 'Condition.code', code: 'Condition.code', text: 'Condition.code-text', display: 'Condition.code-display' },
     Procedure: { field: 'Procedure.code', code: 'Procedure.code', text: 'Procedure.code-text', display: 'Procedure.code-display' },
@@ -42,7 +43,7 @@ async function projectResource(resource, options) {
     const existingMeta = asRecord(resource.meta);
     const existingClaims = asRecord(existingMeta.claims);
     const claims = Object.keys(existingClaims).length
-        ? { ...existingClaims }
+        ? presentationClaims(existingClaims)
         : normalizeClaimsFromFhirResource(resource, {});
     const projection = PRIMARY_CODE_PROJECTIONS[resourceType];
     if (projection) {
@@ -69,6 +70,24 @@ async function projectResource(resource, options) {
         meta: { ...existingMeta, claims },
     };
 }
+/**
+ * Keeps structural FHIR metadata on the resource while preventing derived
+ * paths such as `Immunization.meta.versionId` from becoming editable/search
+ * claims in the presentation copy.
+ */
+function presentationClaims(source) {
+    return Object.fromEntries(Object.entries(source).filter(([claim]) => {
+        if (claim.startsWith('@'))
+            return true;
+        try {
+            normalizeFhirApiClaimKey(claim);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
 function parseCodingToken(value) {
     const separator = value.lastIndexOf('|');
     if (separator <= 0 || separator === value.length - 1)

package/dist/clinical-terminology.d.ts

@@ -1,8 +1,9 @@
+/** @deprecated Import `ClinicalTerminologySystems` from sos-data-utils-ts. */
 export declare const VeterinaryClinicalTerminologySystems: Readonly<{
     readonly Loinc: "http://loinc.org";
     readonly SnomedCt: "http://snomed.info/sct";
     readonly Icd10: "http://hl7.org/fhir/sid/icd-10";
-    /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
+    readonly Atc: "http://www.whocc.no/atc";
     readonly AtcVet: "http://www.whocc.no/atcvet";
 }>;
 /**
@@ -11,15 +12,19 @@ export declare const VeterinaryClinicalTerminologySystems: Readonly<{
  * canonical SNOMED system URI.
  * https://www.snomed.org/gps
  */
+/** @deprecated Import `ClinicalTerminologySourceScopes` from sos-data-utils-ts. */
 export declare const VeterinaryTerminologySourceScopes: Readonly<{
     readonly Loinc: "LNC";
     readonly SnomedGps: "SNOMED_GPS";
+    readonly SnomedIps: "SNOMED_IPS";
     readonly SnomedCt: "SNOMED_CT";
     readonly SnomedVeterinary: "SNOMEDCT_VET";
     readonly Icd10: "ICD10";
+    readonly Atc: "ATC";
     readonly AtcVet: "ATCVET";
 }>;
 /** Deterministic standards-based data for the isolated local terminology upstream. */
+/** @deprecated Import `CLINICAL_TERMINOLOGY_TEST_DATA` from sos-data-utils-ts. */
 export declare const VET_TERMINOLOGY_TEST_DATA: Readonly<{
     readonly localApiKey: "local-playwright-umls-key";
     readonly bodyTemperature: Readonly<{
@@ -35,8 +40,31 @@ export declare const VET_TERMINOLOGY_TEST_DATA: Readonly<{
         code: "3135009";
         display: "otitis externa";
     }>;
+    readonly canineRabiesVaccine: Readonly<{
+        scope: "ATCVET";
+        system: "http://www.whocc.no/atcvet";
+        code: "QI07AA02";
+        text: "virus de la rabia";
+        display: "rabies virus";
+        ncbiTaxonomyId: "9615";
+    }>;
+    readonly humanInactivatedInfluenzaVaccine: Readonly<{
+        scope: "ATC";
+        system: "http://www.whocc.no/atc";
+        code: "J07BB02";
+        text: "vacuna contra la gripe inactivada de virus fraccionados o ant\u00EDgeno de superficie";
+        display: "influenza, inactivated, split virus or surface antigen";
+        ncbiTaxonomyId: "9606";
+    }>;
+    readonly rabiesDisease: Readonly<{
+        scope: "SNOMED_GPS";
+        umlsSource: "SNOMEDCT_US";
+        system: "http://snomed.info/sct";
+        code: "14168008";
+        display: "Rabies";
+    }>;
 }>;
-export type VeterinaryTerminologySourceScope = typeof VeterinaryTerminologySourceScopes[keyof typeof VeterinaryTerminologySourceScopes];
+export type VeterinaryTerminologySourceScope = Exclude<typeof VeterinaryTerminologySourceScopes[keyof typeof VeterinaryTerminologySourceScopes], 'ATC' | 'SNOMED_IPS'>;
 export type VeterinaryTerminologyCapability = Readonly<{
     type: 'terminology-capability';
     id: string;

package/dist/clinical-terminology.js

@@ -1,41 +1,17 @@
-export const VeterinaryClinicalTerminologySystems = Object.freeze({
-    Loinc: 'http://loinc.org',
-    SnomedCt: 'http://snomed.info/sct',
-    Icd10: 'http://hl7.org/fhir/sid/icd-10',
-    /** WHO Collaborating Centre ATCvet classification, distinct from human ATC. */
-    AtcVet: 'http://www.whocc.no/atcvet',
-});
+import { CLINICAL_TERMINOLOGY_TEST_DATA, ClinicalTerminologySourceScopes, ClinicalTerminologySystems, } from 'sos-data-utils-ts/clinical-terminology';
+/** @deprecated Import `ClinicalTerminologySystems` from sos-data-utils-ts. */
+export const VeterinaryClinicalTerminologySystems = ClinicalTerminologySystems;
 /**
  * Source scopes are authorization/content boundaries, not Coding.system URIs.
  * GPS, full SNOMED CT and the veterinary extension intentionally share the
  * canonical SNOMED system URI.
  * https://www.snomed.org/gps
  */
-export const VeterinaryTerminologySourceScopes = Object.freeze({
-    Loinc: 'LNC',
-    SnomedGps: 'SNOMED_GPS',
-    SnomedCt: 'SNOMED_CT',
-    SnomedVeterinary: 'SNOMEDCT_VET',
-    Icd10: 'ICD10',
-    AtcVet: 'ATCVET',
-});
+/** @deprecated Import `ClinicalTerminologySourceScopes` from sos-data-utils-ts. */
+export const VeterinaryTerminologySourceScopes = ClinicalTerminologySourceScopes;
 /** Deterministic standards-based data for the isolated local terminology upstream. */
-export const VET_TERMINOLOGY_TEST_DATA = Object.freeze({
-    localApiKey: 'local-playwright-umls-key',
-    bodyTemperature: Object.freeze({
-        source: VeterinaryTerminologySourceScopes.Loinc,
-        system: VeterinaryClinicalTerminologySystems.Loinc,
-        code: '8310-5',
-        display: 'Body temperature:Temp:Pt:^Patient:Qn',
-    }),
-    otitisExternaSpanish: Object.freeze({
-        scope: VeterinaryTerminologySourceScopes.SnomedCt,
-        umlsSource: 'SCTSPA',
-        system: VeterinaryClinicalTerminologySystems.SnomedCt,
-        code: '3135009',
-        display: 'otitis externa',
-    }),
-});
+/** @deprecated Import `CLINICAL_TERMINOLOGY_TEST_DATA` from sos-data-utils-ts. */
+export const VET_TERMINOLOGY_TEST_DATA = CLINICAL_TERMINOLOGY_TEST_DATA;
 /**
  * ISO 3166-1 alpha-2 territories enumerated by the official SNOMED
  * International member page on 2026-09-05.

package/dist/immunization-coding-review.d.ts

@@ -0,0 +1,51 @@
+import { type FlatClaimCodingCandidate, type FlatClaimCodingReviewResource } from 'fhir-data-utils-ts/coding-review-flat-claims';
+/** Governed claim coordinates reused by Vet gateways, portals and assistants. */
+export declare const VeterinaryImmunizationCodingReviewClaims: Readonly<{
+    code: "Immunization.vaccine-code";
+    display: string;
+    localText: string;
+}>;
+/**
+ * Builds an unconfirmed veterinary Immunization coding review from text spoken,
+ * typed or imported by a channel. The neutral helper owns proposal placement;
+ * this wrapper contributes veterinary resource coordinates and ATCvet policy.
+ */
+export declare function buildVeterinaryImmunizationCodingReview(input: Readonly<{
+    entryId: string;
+    animalReference: string;
+    administrationDate: string;
+    localText: string;
+    language: string;
+    proposalId: string;
+    candidates: readonly FlatClaimCodingCandidate[];
+}>): FlatClaimCodingReviewResource;
+/** Package-owned synthetic example for assistants, portals and downstream tests. */
+export declare const VETERINARY_IMMUNIZATION_CODING_REVIEW_EXAMPLE: Readonly<{
+    input: Readonly<{
+        entryId: "00000000-0000-4000-8000-000000000201";
+        animalReference: "Patient/00000000-0000-4000-8000-000000000202";
+        administrationDate: "2024-05-23";
+        localText: "vacuna contra la rabia";
+        language: "es-ES";
+        proposalId: "veterinary-immunization-proposal-example";
+        candidates: readonly Readonly<{
+            id: "veterinary-immunization-candidate-example";
+            system: "http://www.whocc.no/atcvet";
+            code: "QI07AA02";
+            display: "Inactivated rabies virus vaccines";
+        }>[];
+    }>;
+    claims: Readonly<{
+        code: "Immunization.vaccine-code";
+        display: string;
+        localText: string;
+    }>;
+    expected: Readonly<{
+        resourceType: string;
+        id: string;
+        meta: Readonly<{
+            claims: Readonly<Record<string, string>>;
+            codingProposals?: readonly import("fhir-data-utils-ts/coding-review-flat-claims").FlatClaimCodingProposal[];
+        }>;
+    }>;
+}>;

package/dist/immunization-coding-review.js

@@ -0,0 +1,59 @@
+import { buildFlatClaimCodingReviewResource, deriveCodingDisplayClaim, deriveCodingLocalTextClaim, } from 'fhir-data-utils-ts/coding-review-flat-claims';
+import { VeterinaryClinicalTerminologySystems } from './clinical-terminology.js';
+const IMMUNIZATION_RESOURCE_TYPE = 'Immunization';
+const IMMUNIZATION_VACCINE_CODE_CLAIM = `${IMMUNIZATION_RESOURCE_TYPE}.vaccine-code`;
+/** Governed claim coordinates reused by Vet gateways, portals and assistants. */
+export const VeterinaryImmunizationCodingReviewClaims = Object.freeze({
+    code: IMMUNIZATION_VACCINE_CODE_CLAIM,
+    display: deriveCodingDisplayClaim(IMMUNIZATION_VACCINE_CODE_CLAIM),
+    localText: deriveCodingLocalTextClaim(IMMUNIZATION_VACCINE_CODE_CLAIM),
+});
+/**
+ * Builds an unconfirmed veterinary Immunization coding review from text spoken,
+ * typed or imported by a channel. The neutral helper owns proposal placement;
+ * this wrapper contributes veterinary resource coordinates and ATCvet policy.
+ */
+export function buildVeterinaryImmunizationCodingReview(input) {
+    const candidates = input.candidates.map((candidate) => {
+        if (candidate.system !== VeterinaryClinicalTerminologySystems.AtcVet) {
+            throw new TypeError('veterinary_immunization_candidate_system_invalid');
+        }
+        return candidate;
+    });
+    return buildFlatClaimCodingReviewResource({
+        resourceType: IMMUNIZATION_RESOURCE_TYPE,
+        resourceId: input.entryId,
+        targetClaim: VeterinaryImmunizationCodingReviewClaims.code,
+        localText: input.localText,
+        language: input.language,
+        baseClaims: {
+            'Immunization.status': 'completed',
+            'Immunization.patient': input.animalReference,
+            'Immunization.date': input.administrationDate,
+        },
+        proposalId: input.proposalId,
+        candidates,
+    });
+}
+const EXAMPLE_ENTRY_ID = '00000000-0000-4000-8000-000000000201';
+const EXAMPLE_ANIMAL_ID = '00000000-0000-4000-8000-000000000202';
+const EXAMPLE_INPUT = Object.freeze({
+    entryId: EXAMPLE_ENTRY_ID,
+    animalReference: `Patient/${EXAMPLE_ANIMAL_ID}`,
+    administrationDate: '2024-05-23',
+    localText: 'vacuna contra la rabia',
+    language: 'es-ES',
+    proposalId: 'veterinary-immunization-proposal-example',
+    candidates: Object.freeze([Object.freeze({
+            id: 'veterinary-immunization-candidate-example',
+            system: VeterinaryClinicalTerminologySystems.AtcVet,
+            code: 'QI07AA02',
+            display: 'Inactivated rabies virus vaccines',
+        })]),
+});
+/** Package-owned synthetic example for assistants, portals and downstream tests. */
+export const VETERINARY_IMMUNIZATION_CODING_REVIEW_EXAMPLE = Object.freeze({
+    input: EXAMPLE_INPUT,
+    claims: VeterinaryImmunizationCodingReviewClaims,
+    expected: buildVeterinaryImmunizationCodingReview(EXAMPLE_INPUT),
+});

package/dist/immunization-draft.d.ts

@@ -39,5 +39,5 @@ export declare function confirmVeterinaryImmunizationDraft(draft: VeterinaryImmu
 export declare function materializeVeterinaryImmunizationDraft(draft: VeterinaryImmunizationDraft, context: Readonly<{
     entryId: string;
     animalReference: string;
-    performerReference: string;
+    performerReference?: string;
 }>): readonly FlatClaimResourceEntry[];

package/dist/immunization-draft.js

@@ -46,14 +46,19 @@ export function materializeVeterinaryImmunizationDraft(draft, context) {
     return buildVeterinaryImmunizationFlatGraph({
         entryId: required(context.entryId, 'veterinary_immunization_entry_id_required'),
         animalReference: required(context.animalReference, 'veterinary_immunization_animal_reference_required'),
-        performerReference: required(context.performerReference, 'veterinary_immunization_performer_required'),
+        ...(context.performerReference ? {
+            performerReference: required(context.performerReference, 'veterinary_immunization_performer_invalid'),
+        } : {}),
         administrationDate: draft.administrationDate,
         vaccineCode: draft.vaccineCode,
         targetDiseases: draft.targetDiseases,
         ...(draft.routeCode ? { route: { system: 'http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration', code: draft.routeCode } } : {}),
         ...(draft.siteCode ? { site: { system: 'http://terminology.hl7.org/CodeSystem/v3-ActSite', code: draft.siteCode } } : {}),
         ...(draft.doseValue ? { dose: { value: draft.doseValue, ...(draft.doseUnit ? { unit: draft.doseUnit } : {}) } } : {}),
-        ...(draft.nextDoseDate ? { nextDoseDate: draft.nextDoseDate } : {}),
+        ...(draft.nextDoseDate ? {
+            nextDoseDate: draft.nextDoseDate,
+            recommendationDate: required(draft.confirmedAt, 'veterinary_immunization_confirmation_time_required'),
+        } : {}),
         ...(hasMedication ? { medication: {
                 entryId: `${context.entryId}-medication`,
                 productName: draft.productName || draft.vaccineCode.display || `${draft.vaccineCode.system}|${draft.vaccineCode.code}`,
@@ -75,6 +80,7 @@ function coding(value, error) {
     return Object.freeze({
         system: required(candidate.system, error), code: required(candidate.code, error),
         ...(text(candidate.display) ? { display: text(candidate.display) } : {}),
+        ...(text(candidate.text) ? { text: text(candidate.text) } : {}),
     });
 }
 function date(value, error) {

package/dist/immunization-flat-claims.d.ts

@@ -1,8 +1,15 @@
 import { type FlatClaimResourceEntry } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { type ImmunizationReminderChannel } from 'sos-data-utils-ts/immunization-reminder-plan';
 export type VeterinaryImmunizationCoding = Readonly<{
     system: string;
     code: string;
     display?: string;
+    /**
+     * Canonical requested-language term entered or selected by the channel.
+     * A neutral coding proposal targets `Immunization.vaccine-code`; accepting
+     * it must preserve this value as `Immunization.vaccine-code-text`.
+     */
+    text?: string;
 }>;
 export type VeterinaryImmunizationFlatInput = Readonly<{
     entryId: string;
@@ -10,7 +17,8 @@ export type VeterinaryImmunizationFlatInput = Readonly<{
     animalReference: string;
     administrationDate: string;
     vaccineCode: VeterinaryImmunizationCoding;
-    performerReference: string;
+    /** Present only when the administering professional is known. */
+    performerReference?: string;
     targetDiseases?: readonly VeterinaryImmunizationCoding[];
     route?: VeterinaryImmunizationCoding;
     site?: VeterinaryImmunizationCoding;
@@ -19,6 +27,10 @@ export type VeterinaryImmunizationFlatInput = Readonly<{
         unit?: string;
     }>;
     nextDoseDate?: string;
+    /** FHIR dateTime when the recommendation was created; required with nextDoseDate. */
+    recommendationDate?: string;
+    /** Ordered candidates only; dispatch rechecks current preference and Consent. */
+    reminderChannels?: readonly ImmunizationReminderChannel[];
     medication?: Readonly<{
         entryId: string;
         productName: string;
@@ -36,7 +48,10 @@ export type VeterinaryImmunizationFlatInput = Readonly<{
     attachmentEntryIds?: readonly string[];
 }>;
 /**
- * Creates a version-neutral flat graph. SearchParameter names are preferred
+ * Creates a version-neutral flat graph after coding review is confirmed.
+ * Unconfirmed `meta.codingProposals[]` use the neutral `fhir-data-utils-ts`
+ * contract and remain on the same resource, outside `meta.claims`.
+ * SearchParameter names are preferred
  * (`Immunization.date`, `Medication.expiration-date`) and product evidence is
  * kept in Medication instead of overloading credential validity.
  */

package/dist/immunization-flat-claims.js

@@ -1,6 +1,10 @@
 import { buildDocumentReferenceFlatEntry, buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from 'sos-data-utils-ts/flat-claim-resource-graph';
+import { ImmunizationReminderChannels, buildImmunizationReminderTasks, } from 'sos-data-utils-ts/immunization-reminder-plan';
 /**
- * Creates a version-neutral flat graph. SearchParameter names are preferred
+ * Creates a version-neutral flat graph after coding review is confirmed.
+ * Unconfirmed `meta.codingProposals[]` use the neutral `fhir-data-utils-ts`
+ * contract and remain on the same resource, outside `meta.claims`.
+ * SearchParameter names are preferred
  * (`Immunization.date`, `Medication.expiration-date`) and product evidence is
  * kept in Medication instead of overloading credential validity.
  */
@@ -11,14 +15,24 @@ export function buildVeterinaryImmunizationFlatGraph(input) {
         'Immunization.patient': required(input.animalReference, 'veterinary_immunization_animal_reference_required'),
         'Immunization.date': isoDate(input.administrationDate, 'veterinary_immunization_date_invalid'),
         'Immunization.vaccine-code': vaccineCode,
-        'Immunization.performer': required(input.performerReference, 'veterinary_immunization_performer_required'),
     };
     if (input.identifier)
         claims['Immunization.identifier'] = required(input.identifier, 'veterinary_immunization_identifier_invalid');
     if (input.vaccineCode.display)
         claims['Immunization.vaccine-code-display'] = input.vaccineCode.display.trim();
-    if (input.targetDiseases?.length)
+    if (input.vaccineCode.text)
+        claims['Immunization.vaccine-code-text'] = input.vaccineCode.text.trim();
+    if (input.performerReference)
+        claims['Immunization.performer'] = required(input.performerReference, 'veterinary_immunization_performer_invalid');
+    if (input.targetDiseases?.length) {
         claims['Immunization.target-disease'] = input.targetDiseases.map(codingToken).join(',');
+        if (input.targetDiseases.some(({ display }) => display?.trim())) {
+            claims['Immunization.target-disease-display'] = joinCsv(input.targetDiseases.map(({ display }) => display?.trim() ?? ''));
+        }
+        if (input.targetDiseases.some(({ text }) => text?.trim())) {
+            claims['Immunization.target-disease-text'] = joinCsv(input.targetDiseases.map(({ text }) => text?.trim() ?? ''));
+        }
+    }
     if (input.route)
         claims['Immunization.route'] = codingToken(input.route);
     if (input.site)
@@ -30,18 +44,34 @@ export function buildVeterinaryImmunizationFlatGraph(input) {
     }
     const immunization = buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Immunization', claims });
     const children = [];
+    let recommendationId;
+    let reminderTasks = [];
     if (input.medication)
         children.push(buildMedicationEntry(input.medication));
     if (input.nextDoseDate) {
+        recommendationId = `${input.entryId}-recommendation`;
         children.push(buildFlatClaimResourceEntry({
-            entryId: `${input.entryId}-recommendation`,
+            entryId: recommendationId,
             resourceType: 'ImmunizationRecommendation',
             claims: {
                 'ImmunizationRecommendation.patient': input.animalReference,
-                'ImmunizationRecommendation.date': isoDate(input.nextDoseDate, 'veterinary_immunization_next_dose_date_invalid'),
+                // FHIR date is when the forecast was created, not when coverage ends.
+                'ImmunizationRecommendation.date': isoDate(required(input.recommendationDate, 'veterinary_immunization_recommendation_date_required'), 'veterinary_immunization_recommendation_date_invalid'),
                 'ImmunizationRecommendation.vaccine-code': vaccineCode,
+                'ImmunizationRecommendation.forecast-status': 'http://terminology.hl7.org/CodeSystem/immunization-recommendation-status|due',
+                'ImmunizationRecommendation.date-criterion-code': 'http://loinc.org|30980-7',
+                'ImmunizationRecommendation.date-criterion-value': isoDate(input.nextDoseDate, 'veterinary_immunization_next_dose_date_invalid'),
+                'ImmunizationRecommendation.supporting-immunization': `Immunization/${input.entryId}`,
             },
         }));
+        reminderTasks = buildImmunizationReminderTasks({
+            entryIdPrefix: recommendationId,
+            recommendationReference: `ImmunizationRecommendation/${recommendationId}`,
+            subjectReference: input.animalReference,
+            coverageEndDate: input.nextDoseDate,
+            channelCandidates: input.reminderChannels ?? ImmunizationReminderChannels,
+        });
+        children.push(...reminderTasks);
     }
     for (const attachment of input.attachments ?? []) {
         if (attachment.resourceType !== 'DocumentReference')
@@ -52,11 +82,18 @@ export function buildVeterinaryImmunizationFlatGraph(input) {
     const childEntryIds = [
         ...(input.medication ? [input.medication.entryId] : []),
         ...(input.nextDoseDate ? [`${input.entryId}-recommendation`] : []),
+        ...(input.attachments ?? []).map(({ entryId }) => entryId),
         ...(input.attachmentEntryIds ?? []),
     ];
-    return childEntryIds.length
+    const linkedImmunization = childEntryIds.length
         ? linkFlatClaimResourceEntries(graph, { parentEntryId: input.entryId, childEntryIds })
         : graph;
+    return recommendationId && reminderTasks.length
+        ? linkFlatClaimResourceEntries(linkedImmunization, {
+            parentEntryId: recommendationId,
+            childEntryIds: reminderTasks.map(({ entryId }) => entryId),
+        })
+        : linkedImmunization;
 }
 function buildMedicationEntry(input) {
     const claims = {
@@ -91,23 +128,29 @@ export function exportVeterinaryImmunizationFlatGraph(graph, release) {
 function exportEntry(entry, release, byReference) {
     const claims = entry.claims;
     if (entry.resourceType === 'Immunization') {
-        const vaccineCode = codeableConcept(claims['Immunization.vaccine-code'], claims['Immunization.vaccine-code-display']);
+        const vaccineCode = codeableConcept(claims['Immunization.vaccine-code'], claims['Immunization.vaccine-code-display'], claims['Immunization.vaccine-code-text']);
         const children = splitCsv(claims['Immunization.contained-reference-list']).map((reference) => byReference.get(reference)).filter(Boolean);
         const medication = children.find((child) => child?.resourceType === 'Medication');
         const resource = {
             resourceType: 'Immunization', id: entry.entryId, status: claims['Immunization.status'],
             vaccineCode, patient: { reference: claims['Immunization.patient'] },
             occurrenceDateTime: claims['Immunization.date'],
-            performer: [{ actor: { reference: claims['Immunization.performer'] } }],
         };
+        if (claims['Immunization.performer'])
+            resource.performer = [{ actor: { reference: claims['Immunization.performer'] } }];
         if (claims['Immunization.identifier'])
             resource.identifier = [{ value: claims['Immunization.identifier'] }];
         if (claims['Immunization.route'])
             resource.route = codeableConcept(claims['Immunization.route']);
         if (claims['Immunization.site'])
             resource.site = codeableConcept(claims['Immunization.site']);
-        if (claims['Immunization.target-disease'])
-            resource.protocolApplied = [{ targetDisease: splitCsv(claims['Immunization.target-disease']).map((code) => codeableConcept(code)) }];
+        if (claims['Immunization.target-disease']) {
+            const displays = splitCsvKeepingEmpty(claims['Immunization.target-disease-display']);
+            const texts = splitCsvKeepingEmpty(claims['Immunization.target-disease-text']);
+            resource.protocolApplied = [{
+                    targetDisease: splitCsv(claims['Immunization.target-disease']).map((code, index) => (codeableConcept(code, displays[index], texts[index]))),
+                }];
+        }
         if (medication && release !== 'R4')
             resource.administeredProduct = { reference: { reference: medication.reference } };
         return resource;
@@ -117,7 +160,7 @@ function exportEntry(entry, release, byReference) {
         const expirationDate = claims['Medication.expiration-date'];
         const resource = {
             resourceType: 'Medication', id: entry.entryId,
-            code: codeableConcept(claims['Medication.code'], claims['Medication.code-text']),
+            code: codeableConcept(claims['Medication.code'], undefined, claims['Medication.code-text']),
         };
         if (claims['Medication.identifier'])
             resource.identifier = splitCsv(claims['Medication.identifier']).map(identifierFromToken);
@@ -132,7 +175,15 @@ function exportEntry(entry, release, byReference) {
             resourceType: 'ImmunizationRecommendation', id: entry.entryId,
             patient: { reference: claims['ImmunizationRecommendation.patient'] },
             date: claims['ImmunizationRecommendation.date'],
-            recommendation: [{ vaccineCode: [codeableConcept(claims['ImmunizationRecommendation.vaccine-code'])] }],
+            recommendation: [{
+                    vaccineCode: [codeableConcept(claims['ImmunizationRecommendation.vaccine-code'])],
+                    forecastStatus: codeableConcept(claims['ImmunizationRecommendation.forecast-status']),
+                    dateCriterion: [{
+                            code: codeableConcept(claims['ImmunizationRecommendation.date-criterion-code']),
+                            value: claims['ImmunizationRecommendation.date-criterion-value'],
+                        }],
+                    supportingImmunization: [{ reference: claims['ImmunizationRecommendation.supporting-immunization'] }],
+                }],
         };
     if (entry.resourceType === 'DocumentReference')
         return {
@@ -146,12 +197,15 @@ function exportEntry(entry, release, byReference) {
         };
     return { resourceType: entry.resourceType, id: entry.entryId, meta: { claims: { ...claims } } };
 }
-function codeableConcept(token, display) {
+function codeableConcept(token, display, text) {
     const value = required(token, 'veterinary_coding_required');
     const separator = value.lastIndexOf('|');
     if (separator <= 0 || separator === value.length - 1)
-        return { text: display || value };
-    return { coding: [{ system: value.slice(0, separator), code: value.slice(separator + 1), ...(display ? { display } : {}) }] };
+        return { text: text || display || value };
+    return {
+        coding: [{ system: value.slice(0, separator), code: value.slice(separator + 1), ...(display ? { display } : {}) }],
+        ...(text ? { text } : {}),
+    };
 }
 function identifierFromToken(token) {
     const separator = token.lastIndexOf('|');
@@ -172,7 +226,36 @@ function required(value, error) {
     return value.trim();
 }
 function splitCsv(value) {
-    return value?.split(',').map((item) => item.trim()).filter(Boolean) ?? [];
+    return splitCsvKeepingEmpty(value).filter(Boolean);
+}
+function splitCsvKeepingEmpty(value) {
+    if (value === undefined)
+        return [];
+    const values = [];
+    let current = '';
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character === '"' && quoted && value[index + 1] === '"') {
+            current += '"';
+            index += 1;
+        }
+        else if (character === '"')
+            quoted = !quoted;
+        else if (character === ',' && !quoted) {
+            values.push(current.trim());
+            current = '';
+        }
+        else
+            current += character;
+    }
+    values.push(current.trim());
+    return values;
+}
+function joinCsv(values) {
+    return values.map((value) => value.includes(',') || value.includes('"')
+        ? `"${value.replaceAll('"', '""')}"`
+        : value).join(',');
 }
 function uniqueEntries(entries) {
     const byId = new Map();
@@ -194,9 +277,13 @@ export const NALA_VACCINATION_FLAT_GRAPH_TEST_DATA = uniqueEntries([
     ...buildVeterinaryImmunizationFlatGraph({
         entryId: 'nala-rabies', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
         performerReference: 'PractitionerRole/certificate-veterinarian',
-        vaccineCode: { system: atcVet, code: 'QI07AA02', display: 'Inactivated rabies virus vaccines' },
-        targetDiseases: [{ system: 'http://snomed.info/sct', code: '14168008', display: 'Rabies' }],
+        vaccineCode: {
+            system: atcVet, code: 'QI07AA02', display: 'Inactivated rabies virus vaccines',
+            text: 'Vacuna contra el virus de la rabia',
+        },
+        targetDiseases: [{ system: 'http://snomed.info/sct', code: '14168008', display: 'Rabies', text: 'Rabia' }],
         nextDoseDate: '2027-05-23',
+        recommendationDate: '2026-09-20T12:00:00.000Z',
         medication: {
             entryId: 'nala-rabies-product', productName: 'Imrab 3 TF',
             productCode: { system: atcVet, code: 'QI07AA02' }, manufacturer: 'Boehringer Ingelheim',
@@ -213,12 +300,14 @@ export const NALA_VACCINATION_FLAT_GRAPH_TEST_DATA = uniqueEntries([
         entryId: 'nala-da2plp', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
         performerReference: 'PractitionerRole/certificate-veterinarian',
         vaccineCode: { system: atcVet, code: 'QI07AI02', display: 'Canine viral and bacterial combination vaccines' },
-        nextDoseDate: '2025-05-23', attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+        nextDoseDate: '2025-05-23', recommendationDate: '2026-09-20T12:00:00.000Z',
+        attachments: [certificate], attachmentEntryIds: [certificate.entryId],
     }),
     ...buildVeterinaryImmunizationFlatGraph({
         entryId: 'nala-lyme', animalReference: 'Patient/nala', administrationDate: '2024-05-23',
         performerReference: 'PractitionerRole/certificate-veterinarian',
         vaccineCode: { system: atcVet, code: 'QI07AB04', display: 'Borrelia vaccines' },
-        nextDoseDate: '2025-05-23', attachments: [certificate], attachmentEntryIds: [certificate.entryId],
+        nextDoseDate: '2025-05-23', recommendationDate: '2026-09-20T12:00:00.000Z',
+        attachments: [certificate], attachmentEntryIds: [certificate.entryId],
     }),
 ]);

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './group.js';
 export * from './health-dcat.js';
 export * from './immunization.js';
 export * from './immunization-flat-claims.js';
+export * from './immunization-coding-review.js';
 export * from './immunization-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
@@ -20,6 +21,7 @@ export * from './lost-animal-access.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './professional-access-policy.js';
 export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export * from './group.js';
 export * from './health-dcat.js';
 export * from './immunization.js';
 export * from './immunization-flat-claims.js';
+export * from './immunization-coding-review.js';
 export * from './immunization-draft.js';
 export * from './international-health-card.js';
 export * from './index-projection-tags.js';
@@ -20,6 +21,7 @@ export * from './lost-animal-access.js';
 export * from './organization-application.js';
 export * from './payment.js';
 export * from './place-service-directory.js';
+export * from './professional-access-policy.js';
 export * from './provenance.js';
 export * from './research-study.js';
 export * from './sectors.js';

package/dist/organization-application.d.ts

@@ -7,6 +7,7 @@ export declare const OrganizationParticipationRoles: Readonly<{
     readonly IndividualIndexServiceProvider: "individual-index-service-provider";
     readonly IndividualIndexDataProvider: "individual-index-data-provider";
     readonly IndividualIndexDataConsumer: "individual-index-data-consumer";
+    readonly IndividualPersonalBackupServiceProvider: "individual-personal-backup-service-provider";
     readonly DigitalTwinIndexServiceProvider: "digital-twin-index-service-provider";
     readonly DigitalTwinDataProvider: "digital-twin-data-provider";
     readonly DigitalTwinDataConsumer: "digital-twin-data-consumer";
@@ -35,7 +36,7 @@ export type ReusableOrganizationApplication = Readonly<{
     participationRoles: readonly OrganizationParticipationRole[];
 }>;
 /**
- * Converts the six explicit application roles into GW's canonical capability
+ * Converts the explicit application roles into the shared canonical capability
  * claim. Business roles remain distinct in the application and credential;
  * this projection only grants their corresponding provider or reader runtime
  * operations and removes duplicates.

package/dist/organization-application.js

@@ -1,5 +1,6 @@
 import { isIso3166CountryCode, isIso3166SubdivisionForCountry } from './iso-jurisdictions.js';
 import { serializeServiceCapabilityTokens, ServiceCapability, } from 'gdc-common-utils-ts/constants/service-capabilities';
+import { ContinuityServiceCapability } from 'sos-data-utils-ts/continuity-service-capabilities';
 export const OrganizationOfficialIdTypes = Object.freeze({
     Tax: 'TAX',
     EmployerIdentificationNumber: 'EIN',
@@ -9,6 +10,7 @@ export const OrganizationParticipationRoles = Object.freeze({
     IndividualIndexServiceProvider: 'individual-index-service-provider',
     IndividualIndexDataProvider: 'individual-index-data-provider',
     IndividualIndexDataConsumer: 'individual-index-data-consumer',
+    IndividualPersonalBackupServiceProvider: 'individual-personal-backup-service-provider',
     DigitalTwinIndexServiceProvider: 'digital-twin-index-service-provider',
     DigitalTwinDataProvider: 'digital-twin-data-provider',
     DigitalTwinDataConsumer: 'digital-twin-data-consumer',
@@ -16,7 +18,7 @@ export const OrganizationParticipationRoles = Object.freeze({
 const officialIdTypes = new Set(Object.values(OrganizationOfficialIdTypes));
 const participationRoles = new Set(Object.values(OrganizationParticipationRoles));
 /**
- * Converts the six explicit application roles into GW's canonical capability
+ * Converts the explicit application roles into the shared canonical capability
  * claim. Business roles remain distinct in the application and credential;
  * this projection only grants their corresponding provider or reader runtime
  * operations and removes duplicates.
@@ -29,6 +31,8 @@ export function organizationServiceTypeForParticipationRoles(roles) {
                 return ServiceCapability.IndexProvider;
             case OrganizationParticipationRoles.IndividualIndexDataConsumer:
                 return ServiceCapability.IndexReader;
+            case OrganizationParticipationRoles.IndividualPersonalBackupServiceProvider:
+                return ContinuityServiceCapability.DocumentBackupProvider;
             case OrganizationParticipationRoles.DigitalTwinIndexServiceProvider:
             case OrganizationParticipationRoles.DigitalTwinDataProvider:
                 return ServiceCapability.DigitalTwinProvider;

package/dist/professional-access-policy.d.ts

@@ -0,0 +1,2 @@
+/** Vet compatibility surface; the product-neutral policy is owned by SOS. */
+export * from 'sos-data-utils-ts/professional-access-policy';

package/dist/professional-access-policy.js

@@ -0,0 +1,2 @@
+/** Vet compatibility surface; the product-neutral policy is owned by SOS. */
+export * from 'sos-data-utils-ts/professional-access-policy';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.32",
+  "version": "0.5.37",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -60,6 +60,10 @@
       "types": "./dist/immunization-flat-claims.d.ts",
       "default": "./dist/immunization-flat-claims.js"
     },
+    "./immunization-coding-review": {
+      "types": "./dist/immunization-coding-review.d.ts",
+      "default": "./dist/immunization-coding-review.js"
+    },
     "./immunization-draft": {
       "types": "./dist/immunization-draft.d.ts",
       "default": "./dist/immunization-draft.js"
@@ -100,6 +104,10 @@
       "types": "./dist/place-service-directory.d.ts",
       "default": "./dist/place-service-directory.js"
     },
+    "./professional-access-policy": {
+      "types": "./dist/professional-access-policy.d.ts",
+      "default": "./dist/professional-access-policy.js"
+    },
     "./research-study": {
       "types": "./dist/research-study.d.ts",
       "default": "./dist/research-study.js"
@@ -149,9 +157,10 @@
     "typescript": "^5.5.4"
   },
   "dependencies": {
+    "fhir-data-utils-ts": "0.2.4",
     "gdc-common-utils-ts": "2.9.12",
     "pako": "^2.2.0",
-    "sos-data-utils-ts": "0.3.1"
+    "sos-data-utils-ts": "0.3.7"
   },
   "engines": {
     "node": ">=20"