gdc-common-utils-ts 2.5.8 → 2.5.10

package/dist/claims/claims-helpers-medication-statement.js

@@ -26,10 +26,11 @@ export function setMedicationEffective(claims, value) {
     return setMedicationScalar(claims, MedicationStatementClaim.Effective, value);
 }
 export function getMedicationText(claims) {
-    return getMedicationScalar(claims, MedicationStatementClaim.MedicationText);
+    return getMedicationScalar(claims, MedicationStatementClaim.CodeText)
+        || getMedicationScalar(claims, MedicationStatementClaim.MedicationText);
 }
 export function setMedicationText(claims, value) {
-    return setMedicationScalar(claims, MedicationStatementClaim.MedicationText, value);
+    return setMedicationScalar(claims, MedicationStatementClaim.CodeText, value);
 }
 export function getMedicationDoseQuantityValue(claims) {
     return getMedicationNumber(claims, MedicationStatementClaimsFhirApiExtended.DoseQuantityValue);

package/dist/convert/convert-medication-statement.js

@@ -6,17 +6,25 @@ export function medicationStatementFlatToFhirR4(claims) {
     const subject = requireClaim(claims, MedicationStatementClaim.Subject);
     const status = requireClaim(claims, MedicationStatementClaim.Status);
     const effectiveDateTime = claims[MedicationStatementClaim.Effective];
-    const medicationText = claims[MedicationStatementClaim.MedicationText];
+    const medicationText = claims[MedicationStatementClaim.CodeText]
+        || claims[MedicationStatementClaim.MedicationText];
+    const medicationReference = claims[MedicationStatementClaim.Medication];
     const medicationIdentifier = claims[MedicationStatementClaim.MedicationIdentifier];
     const medicationSerialNumber = claims[MedicationStatementClaim.MedicationSerialNumber];
     const medicationExpirationDate = claims[MedicationStatementClaim.MedicationExpirationDate];
-    const hasContainedMedication = Boolean(medicationIdentifier) || Boolean(medicationSerialNumber) || Boolean(medicationExpirationDate) || Boolean(medicationText);
+    const hasContainedMedication = Boolean(medicationIdentifier) || Boolean(medicationSerialNumber) || Boolean(medicationExpirationDate);
     const containedMedicationId = 'medication-contained-1';
     const containedMedication = hasContainedMedication ? {
         resourceType: 'Medication',
         id: containedMedicationId,
         identifier: medicationIdentifier ? [{ value: medicationIdentifier }] : undefined,
-        code: medicationText ? { text: medicationText } : undefined,
+        code: claims[MedicationStatementClaim.Code] || medicationText ? {
+            coding: codingFromValue(claims[MedicationStatementClaim.Code])?.map((coding) => ({
+                ...coding,
+                ...(claims[MedicationStatementClaim.CodeDisplay] ? { display: claims[MedicationStatementClaim.CodeDisplay] } : {}),
+            })),
+            ...(medicationText ? { text: medicationText } : {}),
+        } : undefined,
         batch: medicationSerialNumber || medicationExpirationDate ? {
             lotNumber: medicationSerialNumber,
             expirationDate: medicationExpirationDate,
@@ -35,7 +43,7 @@ export function medicationStatementFlatToFhirR4(claims) {
         status,
         subject: { reference: subject },
         effectiveDateTime,
-        medicationCodeableConcept: claims[MedicationStatementClaim.Code]
+        medicationCodeableConcept: !medicationReference && !hasContainedMedication && claims[MedicationStatementClaim.Code]
             ? {
                 coding: codingFromValue(claims[MedicationStatementClaim.Code])?.map((coding) => ({
                     ...coding,
@@ -43,8 +51,10 @@ export function medicationStatementFlatToFhirR4(claims) {
                 })),
                 ...(medicationText ? { text: medicationText } : {}),
             }
-            : (!hasContainedMedication && medicationText ? { text: medicationText } : undefined),
-        medicationReference: hasContainedMedication ? { reference: `#${containedMedicationId}` } : undefined,
+            : (!medicationReference && !hasContainedMedication && medicationText ? { text: medicationText } : undefined),
+        medicationReference: medicationReference
+            ? { reference: medicationReference }
+            : (hasContainedMedication ? { reference: `#${containedMedicationId}` } : undefined),
         contained: containedMedication ? [containedMedication] : undefined,
         informationSource: claims[MedicationStatementClaim.Source] ? { reference: claims[MedicationStatementClaim.Source] } : undefined,
         dosage: hasDosage ? [{
@@ -71,10 +81,11 @@ export function medicationStatementFhirR4ToFlat(resource) {
         ? containedResources.find((item) => item?.resourceType === 'Medication' && String(item?.id || '') === medicationReference.slice(1))
         : containedResources.find((item) => item?.resourceType === 'Medication');
     const containedMedicationIdentifier = containedMedication?.identifier?.[0]?.value;
-    const containedMedicationText = containedMedication?.code?.text;
+    const containedMedicationConcept = containedMedication?.code;
+    const containedMedicationText = containedMedicationConcept?.text;
     const batch = containedMedication?.batch;
     const medicationConcept = resource.medicationCodeableConcept;
-    const medicationCode = codingToValue(medicationConcept?.coding?.[0]);
+    const medicationCode = codingToValue(medicationConcept?.coding?.[0] || containedMedicationConcept?.coding?.[0]);
     const medicationText = containedMedicationText || medicationConcept?.text || undefined;
     const dosage = resource.dosage?.[0];
     const repeat = dosage?.timing
@@ -88,8 +99,9 @@ export function medicationStatementFhirR4ToFlat(resource) {
         [MedicationStatementClaim.Status]: resource.status,
         [MedicationStatementClaim.Effective]: resource.effectiveDateTime,
         [MedicationStatementClaim.Code]: medicationCode,
-        [MedicationStatementClaim.MedicationText]: medicationText,
-        [MedicationStatementClaim.CodeDisplay]: medicationConcept?.coding?.[0]?.display,
+        [MedicationStatementClaim.CodeText]: medicationText,
+        [MedicationStatementClaim.Medication]: medicationReference?.startsWith('#') ? undefined : medicationReference,
+        [MedicationStatementClaim.CodeDisplay]: medicationConcept?.coding?.[0]?.display || containedMedicationConcept?.coding?.[0]?.display,
         [MedicationStatementClaim.Note]: resource.note?.[0]?.text,
         [MedicationStatementClaim.DosageInstruction]: resource.dosage?.[0]?.text,
         [MedicationStatementClaim.Source]: resource.informationSource?.reference,

package/dist/examples/communication-attached-bundle-session.js

@@ -75,7 +75,7 @@ export function buildMedicationEditingCommunicationSessionExample() {
             [MedicationStatementClaim.Identifier]: EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER,
             [MedicationStatementClaim.Subject]: EXAMPLE_SUBJECT_DID,
             [MedicationStatementClaim.Status]: EXAMPLE_MEDICATION_STATEMENT_STATUS,
-            [MedicationStatementClaim.MedicationText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
+            [MedicationStatementClaim.CodeText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
         },
         fullUrl: `urn:uuid:${EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER}`,
     });

package/dist/examples/ips-bundle.js

@@ -59,7 +59,7 @@ export function buildIpsClinicalHistoryBundleExample() {
             [MedicationStatementClaim.Subject]: EXAMPLE_SUBJECT_DID,
             [MedicationStatementClaim.Category]: HealthcareBasicSections.HistoryOfMedicationUse.attributeValue,
             [MedicationStatementClaim.Status]: EXAMPLE_MEDICATION_STATEMENT_STATUS,
-            [MedicationStatementClaim.MedicationText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
+            [MedicationStatementClaim.CodeText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
             [MedicationStatementClaim.Effective]: '2026-05-05',
         },
         fullUrl: `urn:uuid:${EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER}`,

package/dist/examples/shared.js

@@ -693,7 +693,7 @@ export function buildExampleMedicationIpsDocumentBundle(input) {
         [MedicationStatementClaim.Identifier]: input.medication.identifier,
         [MedicationStatementClaim.Subject]: subjectDid,
         [MedicationStatementClaim.Status]: EXAMPLE_MEDICATION_STATEMENT_STATUS,
-        [MedicationStatementClaim.MedicationText]: input.medication.text,
+        [MedicationStatementClaim.CodeText]: input.medication.text,
         [MedicationStatementClaim.Effective]: input.medication.effectiveDateTime,
         [MedicationStatementClaim.Note]: input.medication.note,
         [MedicationStatementClaim.Category]: input.medication.section || HealthcareBasicSections.HistoryOfMedicationUse.attributeValue,

package/dist/models/interoperable-claims/medication-statement-claims.d.ts

@@ -1,3 +1,26 @@
+import type { ClaimSpec } from './types';
+/** Canonical FHIR R5 code system for `MedicationStatement.adherence.code`. */
+export declare const MEDICATION_STATEMENT_ADHERENCE_CODE_SYSTEM: "http://hl7.org/fhir/CodeSystem/medication-statement-adherence";
+/**
+ * Codes published by the FHIR R5 Medication Statement Adherence value set.
+ *
+ * The FHIR binding strength is `example`, so applications must accept other
+ * valid Coding values even when these helpers cover the published code system.
+ */
+export declare const MedicationStatementAdherenceCodes: {
+    readonly Taking: "taking";
+    readonly TakingAsDirected: "taking-as-directed";
+    readonly TakingNotAsDirected: "taking-not-as-directed";
+    readonly NotTaking: "not-taking";
+    readonly OnHold: "on-hold";
+    readonly OnHoldAsDirected: "on-hold-as-directed";
+    readonly OnHoldNotAsDirected: "on-hold-not-as-directed";
+    readonly Stopped: "stopped";
+    readonly StoppedAsDirected: "stopped-as-directed";
+    readonly StoppedNotAsDirected: "stopped-not-as-directed";
+    readonly Unknown: "unknown";
+};
+export type MedicationStatementAdherenceCode = typeof MedicationStatementAdherenceCodes[keyof typeof MedicationStatementAdherenceCodes];
 /**
  * Canonical flat claim keys for the lightweight `MedicationStatement.*` mapping
  * used by shared examples, GW ingestion, and converter roundtrip tests.
@@ -9,13 +32,26 @@ export declare const MedicationStatementClaim: {
     readonly Status: "MedicationStatement.status";
     readonly Category: "MedicationStatement.category";
     readonly Effective: "MedicationStatement.effective";
+    /** Official token SearchParameter `code`; maps to the medication concept, not a root FHIR element. */
     readonly Code: "MedicationStatement.code";
+    /** Local/manual `CodeableConcept.text` companion for the medication concept. */
+    readonly CodeText: "MedicationStatement.code-text";
+    /** Readable alias for frontend authors; the emitted claim remains `MedicationStatement.code-text`. */
+    readonly CodeTextLocal: "MedicationStatement.code-text";
+    /** Terminology `Coding.display` companion for the medication concept. */
+    readonly CodeDisplay: "MedicationStatement.code-display";
+    /** Official reference SearchParameter; maps to `medication.reference`. */
     readonly Medication: "MedicationStatement.medication";
     readonly PartOf: "MedicationStatement.part-of";
     readonly Source: "MedicationStatement.source";
+    /** @deprecated Use `CodeText`; retained only for historical payload readback. */
     readonly MedicationText: "MedicationStatement.medication-text";
-    /** English/international display for the coded medication. */
-    readonly CodeDisplay: "MedicationStatement.code-display";
+    /** Official R5 token SearchParameter; its FHIRPath expression targets the adherence CodeableConcept. */
+    readonly Adherence: "MedicationStatement.adherence";
+    /** Local/manual CodeableConcept.text companion for the official `adherence` token. */
+    readonly AdherenceText: "MedicationStatement.adherence-text";
+    /** Terminology Coding.display companion for the official `adherence` token. */
+    readonly AdherenceDisplay: "MedicationStatement.adherence-display";
     readonly UserSelected: "MedicationStatement.user-selected";
     /**
      * Free-text clinical note.
@@ -68,6 +104,8 @@ export declare const MedicationStatementClaim: {
     readonly TimingPeriod: "MedicationStatement.timing-period";
     readonly TimingPeriodUnit: "MedicationStatement.timing-period-unit";
 };
+export type MedicationStatementClaimKey = typeof MedicationStatementClaim[keyof typeof MedicationStatementClaim];
+export declare const MedicationStatementClaimSpecs: ClaimSpec[];
 /**
  * Flat claims contract for MedicationStatement using FHIR API-like search params.
  *
@@ -81,6 +119,7 @@ export declare const MedicationStatementClaim: {
  * @basedon https://hl7.org/fhir/medicationstatement.html#search
  */
 export declare enum MedicationStatementClaimsFhirApi {
+    Adherence = "org.hl7.fhir.api.MedicationStatement.adherence",
     Category = "org.hl7.fhir.api.MedicationStatement.category",
     Code = "org.hl7.fhir.api.MedicationStatement.code",
     Effective = "org.hl7.fhir.api.MedicationStatement.effective",
@@ -97,6 +136,11 @@ export declare enum MedicationStatementClaimsFhirApi {
  * These are intentionally scalarized to map cleanly to SQL columns.
  */
 export declare enum MedicationStatementClaimsFhirApiExtended {
+    Adherence = "org.hl7.fhir.api.MedicationStatement.adherence",
+    AdherenceText = "org.hl7.fhir.api.MedicationStatement.adherence-text",
+    AdherenceDisplay = "org.hl7.fhir.api.MedicationStatement.adherence-display",
+    CodeText = "org.hl7.fhir.api.MedicationStatement.code-text",
+    CodeDisplay = "org.hl7.fhir.api.MedicationStatement.code-display",
     Category = "org.hl7.fhir.api.MedicationStatement.category",
     Code = "org.hl7.fhir.api.MedicationStatement.code",
     Effective = "org.hl7.fhir.api.MedicationStatement.effective",
@@ -174,6 +218,7 @@ export declare enum MedicationStatementClaimsFhirApiExtended {
  * by query builders and frontend filters.
  */
 export declare const MedicationStatementSearchParamNames: {
+    readonly Adherence: "adherence";
     readonly Category: "category";
     readonly Code: "code";
     readonly Effective: "effective";
@@ -248,6 +293,7 @@ export declare const MedicationStatementSearchParamNames: {
 export type MedicationStatementSearchParamName = typeof MedicationStatementSearchParamNames[keyof typeof MedicationStatementSearchParamNames];
 export declare const MedicationStatementSearchParamToClaimKey: Record<MedicationStatementSearchParamName, MedicationStatementClaimsFhirApi | MedicationStatementClaimsFhirApiExtended>;
 export declare const MedicationStatementClaimsFhirApiMap: {
+    "org.hl7.fhir.api.MedicationStatement.adherence": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.category": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.code": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.effective": StringConstructor;
@@ -260,6 +306,10 @@ export declare const MedicationStatementClaimsFhirApiMap: {
     "org.hl7.fhir.api.MedicationStatement.subject": StringConstructor;
 };
 export declare const MedicationStatementClaimsFhirApiExtendedMap: {
+    "org.hl7.fhir.api.MedicationStatement.adherence-text": StringConstructor;
+    "org.hl7.fhir.api.MedicationStatement.adherence-display": StringConstructor;
+    "org.hl7.fhir.api.MedicationStatement.code-text": StringConstructor;
+    "org.hl7.fhir.api.MedicationStatement.code-display": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.dose-quantity": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.dose-quantity-value": NumberConstructor;
     "org.hl7.fhir.api.MedicationStatement.dose-quantity-unit": StringConstructor;
@@ -320,6 +370,7 @@ export declare const MedicationStatementClaimsFhirApiExtendedMap: {
     "org.hl7.fhir.api.MedicationStatement.timing-bounds-range-high": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.timing-bounds-range-high-value": NumberConstructor;
     "org.hl7.fhir.api.MedicationStatement.timing-bounds-range-high-unit": StringConstructor;
+    "org.hl7.fhir.api.MedicationStatement.adherence": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.category": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.code": StringConstructor;
     "org.hl7.fhir.api.MedicationStatement.effective": StringConstructor;
@@ -337,6 +388,7 @@ export declare const MedicationStatementClaimsFhirApiExtendedMap: {
  */
 export interface MedicationStatementClaimsFlat {
     '@context'?: 'org.hl7.fhir.api';
+    [MedicationStatementClaimsFhirApi.Adherence]?: string;
     [MedicationStatementClaimsFhirApi.Category]?: string;
     [MedicationStatementClaimsFhirApi.Code]?: string;
     [MedicationStatementClaimsFhirApi.Effective]?: string;
@@ -347,6 +399,10 @@ export interface MedicationStatementClaimsFlat {
     [MedicationStatementClaimsFhirApi.Source]?: string;
     [MedicationStatementClaimsFhirApi.Status]?: string;
     [MedicationStatementClaimsFhirApi.Subject]?: string;
+    [MedicationStatementClaimsFhirApiExtended.AdherenceText]?: string;
+    [MedicationStatementClaimsFhirApiExtended.AdherenceDisplay]?: string;
+    [MedicationStatementClaimsFhirApiExtended.CodeText]?: string;
+    [MedicationStatementClaimsFhirApiExtended.CodeDisplay]?: string;
     [MedicationStatementClaimsFhirApiExtended.DoseQuantity]?: string;
     [MedicationStatementClaimsFhirApiExtended.DoseQuantityValue]?: number;
     [MedicationStatementClaimsFhirApiExtended.DoseQuantityUnit]?: string;
@@ -395,8 +451,13 @@ export interface MedicationStatementClaimsFlat {
  */
 export interface MedicationStatementClaimsContextualized {
     '@context': 'org.hl7.fhir.api';
+    'MedicationStatement.adherence'?: string;
+    'MedicationStatement.adherence-text'?: string;
+    'MedicationStatement.adherence-display'?: string;
     'MedicationStatement.category'?: string;
     'MedicationStatement.code'?: string;
+    'MedicationStatement.code-text'?: string;
+    'MedicationStatement.code-display'?: string;
     'MedicationStatement.effective'?: string;
     'MedicationStatement.identifier'?: string;
     'MedicationStatement.medication'?: string;

package/dist/models/interoperable-claims/medication-statement-claims.js

@@ -1,5 +1,26 @@
 // src/models/fhir/MedicationStatement.claims.ts
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+/** Canonical FHIR R5 code system for `MedicationStatement.adherence.code`. */
+export const MEDICATION_STATEMENT_ADHERENCE_CODE_SYSTEM = 'http://hl7.org/fhir/CodeSystem/medication-statement-adherence';
+/**
+ * Codes published by the FHIR R5 Medication Statement Adherence value set.
+ *
+ * The FHIR binding strength is `example`, so applications must accept other
+ * valid Coding values even when these helpers cover the published code system.
+ */
+export const MedicationStatementAdherenceCodes = {
+    Taking: 'taking',
+    TakingAsDirected: 'taking-as-directed',
+    TakingNotAsDirected: 'taking-not-as-directed',
+    NotTaking: 'not-taking',
+    OnHold: 'on-hold',
+    OnHoldAsDirected: 'on-hold-as-directed',
+    OnHoldNotAsDirected: 'on-hold-not-as-directed',
+    Stopped: 'stopped',
+    StoppedAsDirected: 'stopped-as-directed',
+    StoppedNotAsDirected: 'stopped-not-as-directed',
+    Unknown: 'unknown',
+};
 /**
  * Canonical flat claim keys for the lightweight `MedicationStatement.*` mapping
  * used by shared examples, GW ingestion, and converter roundtrip tests.
@@ -11,13 +32,26 @@ export const MedicationStatementClaim = {
     Status: 'MedicationStatement.status',
     Category: 'MedicationStatement.category',
     Effective: 'MedicationStatement.effective',
+    /** Official token SearchParameter `code`; maps to the medication concept, not a root FHIR element. */
     Code: 'MedicationStatement.code',
+    /** Local/manual `CodeableConcept.text` companion for the medication concept. */
+    CodeText: 'MedicationStatement.code-text',
+    /** Readable alias for frontend authors; the emitted claim remains `MedicationStatement.code-text`. */
+    CodeTextLocal: 'MedicationStatement.code-text',
+    /** Terminology `Coding.display` companion for the medication concept. */
+    CodeDisplay: 'MedicationStatement.code-display',
+    /** Official reference SearchParameter; maps to `medication.reference`. */
     Medication: 'MedicationStatement.medication',
     PartOf: 'MedicationStatement.part-of',
     Source: 'MedicationStatement.source',
+    /** @deprecated Use `CodeText`; retained only for historical payload readback. */
     MedicationText: 'MedicationStatement.medication-text',
-    /** English/international display for the coded medication. */
-    CodeDisplay: 'MedicationStatement.code-display',
+    /** Official R5 token SearchParameter; its FHIRPath expression targets the adherence CodeableConcept. */
+    Adherence: 'MedicationStatement.adherence',
+    /** Local/manual CodeableConcept.text companion for the official `adherence` token. */
+    AdherenceText: 'MedicationStatement.adherence-text',
+    /** Terminology Coding.display companion for the official `adherence` token. */
+    AdherenceDisplay: 'MedicationStatement.adherence-display',
     UserSelected: 'MedicationStatement.user-selected',
     /**
      * Free-text clinical note.
@@ -70,6 +104,15 @@ export const MedicationStatementClaim = {
     TimingPeriod: 'MedicationStatement.timing-period',
     TimingPeriodUnit: 'MedicationStatement.timing-period-unit',
 };
+export const MedicationStatementClaimSpecs = [
+    { key: MedicationStatementClaim.Code, meaning: 'Official token SearchParameter for medication.concept.', example: 'http://www.nlm.nih.gov/research/umls/rxnorm|5640' },
+    { key: MedicationStatementClaim.CodeText, meaning: 'Local/manual medication concept text matching resource language.', example: 'Ibuprofeno' },
+    { key: MedicationStatementClaim.CodeDisplay, meaning: 'Canonical/international medication Coding.display.', example: 'Ibuprofen' },
+    { key: MedicationStatementClaim.Medication, meaning: 'Official reference SearchParameter for medication.reference.', example: 'Medication/medication-123' },
+    { key: MedicationStatementClaim.Adherence, meaning: 'Official R5 adherence token SearchParameter.', example: `${MEDICATION_STATEMENT_ADHERENCE_CODE_SYSTEM}|taking-as-directed` },
+    { key: MedicationStatementClaim.AdherenceText, meaning: 'Local/manual adherence CodeableConcept.text.', example: 'Tomando según indicación' },
+    { key: MedicationStatementClaim.AdherenceDisplay, meaning: 'Canonical adherence Coding.display.', example: 'Taking As Directed' },
+];
 /**
  * Flat claims contract for MedicationStatement using FHIR API-like search params.
  *
@@ -84,6 +127,7 @@ export const MedicationStatementClaim = {
  */
 export var MedicationStatementClaimsFhirApi;
 (function (MedicationStatementClaimsFhirApi) {
+    MedicationStatementClaimsFhirApi["Adherence"] = "org.hl7.fhir.api.MedicationStatement.adherence";
     MedicationStatementClaimsFhirApi["Category"] = "org.hl7.fhir.api.MedicationStatement.category";
     MedicationStatementClaimsFhirApi["Code"] = "org.hl7.fhir.api.MedicationStatement.code";
     MedicationStatementClaimsFhirApi["Effective"] = "org.hl7.fhir.api.MedicationStatement.effective";
@@ -101,6 +145,11 @@ export var MedicationStatementClaimsFhirApi;
  */
 export var MedicationStatementClaimsFhirApiExtended;
 (function (MedicationStatementClaimsFhirApiExtended) {
+    MedicationStatementClaimsFhirApiExtended["Adherence"] = "org.hl7.fhir.api.MedicationStatement.adherence";
+    MedicationStatementClaimsFhirApiExtended["AdherenceText"] = "org.hl7.fhir.api.MedicationStatement.adherence-text";
+    MedicationStatementClaimsFhirApiExtended["AdherenceDisplay"] = "org.hl7.fhir.api.MedicationStatement.adherence-display";
+    MedicationStatementClaimsFhirApiExtended["CodeText"] = "org.hl7.fhir.api.MedicationStatement.code-text";
+    MedicationStatementClaimsFhirApiExtended["CodeDisplay"] = "org.hl7.fhir.api.MedicationStatement.code-display";
     MedicationStatementClaimsFhirApiExtended["Category"] = "org.hl7.fhir.api.MedicationStatement.category";
     MedicationStatementClaimsFhirApiExtended["Code"] = "org.hl7.fhir.api.MedicationStatement.code";
     MedicationStatementClaimsFhirApiExtended["Effective"] = "org.hl7.fhir.api.MedicationStatement.effective";
@@ -181,6 +230,7 @@ export var MedicationStatementClaimsFhirApiExtended;
  * by query builders and frontend filters.
  */
 export const MedicationStatementSearchParamNames = {
+    Adherence: 'adherence',
     Category: 'category',
     Code: 'code',
     Effective: 'effective',
@@ -253,6 +303,7 @@ export const MedicationStatementSearchParamNames = {
     TimingBoundsRangeHighUnit: 'timing-bounds-range-high-unit',
 };
 export const MedicationStatementSearchParamToClaimKey = {
+    [MedicationStatementSearchParamNames.Adherence]: MedicationStatementClaimsFhirApi.Adherence,
     [MedicationStatementSearchParamNames.Category]: MedicationStatementClaimsFhirApi.Category,
     [MedicationStatementSearchParamNames.Code]: MedicationStatementClaimsFhirApi.Code,
     [MedicationStatementSearchParamNames.Effective]: MedicationStatementClaimsFhirApi.Effective,
@@ -325,6 +376,7 @@ export const MedicationStatementSearchParamToClaimKey = {
     [MedicationStatementSearchParamNames.TimingBoundsRangeHighUnit]: MedicationStatementClaimsFhirApiExtended.TimingBoundsRangeHighUnit,
 };
 export const MedicationStatementClaimsFhirApiMap = {
+    [MedicationStatementClaimsFhirApi.Adherence]: String,
     [MedicationStatementClaimsFhirApi.Category]: String,
     [MedicationStatementClaimsFhirApi.Code]: String,
     [MedicationStatementClaimsFhirApi.Effective]: String,
@@ -338,6 +390,10 @@ export const MedicationStatementClaimsFhirApiMap = {
 };
 export const MedicationStatementClaimsFhirApiExtendedMap = {
     ...MedicationStatementClaimsFhirApiMap,
+    [MedicationStatementClaimsFhirApiExtended.AdherenceText]: String,
+    [MedicationStatementClaimsFhirApiExtended.AdherenceDisplay]: String,
+    [MedicationStatementClaimsFhirApiExtended.CodeText]: String,
+    [MedicationStatementClaimsFhirApiExtended.CodeDisplay]: String,
     [MedicationStatementClaimsFhirApiExtended.DoseQuantity]: String,
     [MedicationStatementClaimsFhirApiExtended.DoseQuantityValue]: Number,
     [MedicationStatementClaimsFhirApiExtended.DoseQuantityUnit]: String,

package/dist/utils/clinical-resource-view.js

@@ -374,8 +374,8 @@ function resolveTitle(resourceType, claims, resource, options = {}) {
     }
     if (resourceType === ResourceTypesFhirR4.MedicationStatement) {
         const text = firstClaimValue(claims, [
+            MedicationStatementClaim.CodeText,
             MedicationStatementClaim.MedicationText,
-            MedicationStatementClaimsFhirApi.Medication,
         ]);
         const codeText = findFirstClaimBySuffixes(claims, ['.code-text', '.code-text-local', '.codetextlocal']);
         const codeDisplay = findFirstClaimBySuffixes(claims, ['.code-display', '.codedisplay']);

package/dist/utils/connected-device-fhir-r4.d.ts

@@ -0,0 +1,79 @@
+import type { FhirResource } from '../convert/convert-shared';
+export declare const FHIR_R4_PATIENT_ANIMAL_EXTENSION_URL = "http://hl7.org/fhir/StructureDefinition/patient-animal";
+export type ConnectedDeviceSubjectKind = 'animal' | 'person';
+export type ConnectedDeviceFhirR4Bundle = Readonly<{
+    resourceType: 'Bundle';
+    type: 'transaction';
+    entry: Array<{
+        fullUrl?: string;
+        resource: FhirResource;
+        request: {
+            method: 'PUT';
+            url: string;
+        };
+    }>;
+}>;
+export type ConnectedDeviceObservationInput = Readonly<{
+    id: string;
+    identifierSystem: string;
+    identifierValue: string;
+    status: 'final' | 'amended' | 'corrected';
+    codeSystem: string;
+    code: string;
+    display?: string;
+    effectiveDateTime: string;
+    value: number;
+    unit: string;
+    unitSystem: string;
+    unitCode: string;
+}>;
+export type BuildConnectedDeviceFhirR4BundleInput = Readonly<{
+    subjectKind: ConnectedDeviceSubjectKind;
+    subjectIdentifierSystem: string;
+    subjectIdentifier: string;
+    subjectResourceId: string;
+    animalSpecies?: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+    }>;
+    organizationReference: string;
+    device: Readonly<{
+        id: string;
+        identifierSystem: string;
+        identifierValue: string;
+        manufacturer?: string;
+        modelNumber?: string;
+    }>;
+    observations: readonly ConnectedDeviceObservationInput[];
+}>;
+export type NormalizedConnectedDeviceFhirR4Bundle = Readonly<{
+    subjectIdentifier: string;
+    subjectKind: ConnectedDeviceSubjectKind;
+    device: Readonly<{
+        resource: FhirResource;
+        claims: Readonly<Record<string, string>>;
+    }>;
+    observations: readonly Readonly<{
+        resource: FhirResource;
+        claims: Readonly<Record<string, string>>;
+    }>[];
+    provenance: readonly FhirResource[];
+    sourceBundle: ConnectedDeviceFhirR4Bundle;
+}>;
+/**
+ * Builds the minimum FHIR R4 transaction accepted from a device manufacturer
+ * or clinic. `Patient` is the interoperable wire resource for either subject
+ * kind; it does not replace the internal neutral Subject model.
+ */
+export declare function buildConnectedDeviceFhirR4Bundle(input: BuildConnectedDeviceFhirR4BundleInput): ConnectedDeviceFhirR4Bundle;
+/**
+ * Validates exact subject, Device, Observation and Provenance references, then
+ * projects registered clinical resources into scalar flat claims. Consent and
+ * SMART checks remain gateway responsibilities and must run before indexing.
+ */
+export declare function normalizeConnectedDeviceFhirR4Bundle(bundle: ConnectedDeviceFhirR4Bundle, options: Readonly<{
+    expectedSubjectIdentifier: string;
+    expectedSubjectIdentifierSystem: string;
+    expectedSubjectKind: ConnectedDeviceSubjectKind;
+}>): NormalizedConnectedDeviceFhirR4Bundle;

package/dist/utils/connected-device-fhir-r4.js

@@ -0,0 +1,211 @@
+import { deviceFhirR4ToFlat } from '../convert/convert-device.js';
+import { observationToFlatFhirR4 } from '../convert/convert-observation.js';
+export const FHIR_R4_PATIENT_ANIMAL_EXTENSION_URL = 'http://hl7.org/fhir/StructureDefinition/patient-animal';
+/**
+ * Builds the minimum FHIR R4 transaction accepted from a device manufacturer
+ * or clinic. `Patient` is the interoperable wire resource for either subject
+ * kind; it does not replace the internal neutral Subject model.
+ */
+export function buildConnectedDeviceFhirR4Bundle(input) {
+    assertStableIdentifier(input.subjectIdentifier, 'subjectIdentifier');
+    assertStableIdentifier(input.subjectIdentifierSystem, 'subjectIdentifierSystem');
+    assertId(input.subjectResourceId, 'subjectResourceId');
+    assertReference(input.organizationReference, 'organizationReference');
+    assertId(input.device.id, 'device.id');
+    if (!input.device.identifierSystem.trim() || !input.device.identifierValue.trim()) {
+        throw new Error('Connected Device requires identifier system and value.');
+    }
+    if (input.subjectKind === 'animal' && (!input.animalSpecies?.system.trim() || !input.animalSpecies.code.trim())) {
+        throw new Error('Animal FHIR Patient projection requires patient-animal species coding.');
+    }
+    if (input.observations.length === 0)
+        throw new Error('Connected Device bundle requires at least one Observation.');
+    const patientReference = `Patient/${input.subjectResourceId}`;
+    const deviceReference = `Device/${input.device.id}`;
+    const patient = {
+        resourceType: 'Patient',
+        id: input.subjectResourceId,
+        identifier: [{ system: input.subjectIdentifierSystem, value: input.subjectIdentifier }],
+        ...(input.subjectKind === 'animal'
+            ? {
+                extension: [{
+                        url: FHIR_R4_PATIENT_ANIMAL_EXTENSION_URL,
+                        extension: [{
+                                url: 'species',
+                                valueCodeableConcept: { coding: [{ ...input.animalSpecies }] },
+                            }],
+                    }],
+            }
+            : {}),
+    };
+    const device = {
+        resourceType: 'Device',
+        id: input.device.id,
+        identifier: [{ system: input.device.identifierSystem, value: input.device.identifierValue }],
+        status: 'active',
+        patient: { reference: patientReference },
+        owner: { reference: input.organizationReference },
+        ...(input.device.manufacturer ? { manufacturer: input.device.manufacturer } : {}),
+        ...(input.device.modelNumber ? { modelNumber: input.device.modelNumber } : {}),
+    };
+    const observations = input.observations.map((observation) => buildObservation(observation, patientReference, deviceReference, input.organizationReference));
+    const provenance = {
+        resourceType: 'Provenance',
+        id: 'device-measurement-provenance',
+        target: observations.map((observation) => ({ reference: `Observation/${String(observation.id)}` })),
+        recorded: input.observations.map((observation) => observation.effectiveDateTime).sort().at(-1),
+        agent: [{ type: { text: 'author' }, who: { reference: input.organizationReference } }],
+        entity: [{ role: 'source', what: { reference: deviceReference } }],
+    };
+    const resources = [patient, device, ...observations, provenance];
+    return {
+        resourceType: 'Bundle',
+        type: 'transaction',
+        entry: resources.map((resource) => ({
+            resource,
+            request: { method: 'PUT', url: `${resource.resourceType}/${String(resource.id)}` },
+        })),
+    };
+}
+/**
+ * Validates exact subject, Device, Observation and Provenance references, then
+ * projects registered clinical resources into scalar flat claims. Consent and
+ * SMART checks remain gateway responsibilities and must run before indexing.
+ */
+export function normalizeConnectedDeviceFhirR4Bundle(bundle, options) {
+    if (bundle?.resourceType !== 'Bundle' || bundle.type !== 'transaction' || !Array.isArray(bundle.entry)) {
+        throw new Error('Connected Device payload must be a FHIR R4 transaction Bundle.');
+    }
+    const resources = bundle.entry.map((entry) => entry.resource);
+    const patient = requireExactlyOne(resources, 'Patient');
+    const device = requireExactlyOne(resources, 'Device');
+    const observations = resources.filter((resource) => resource.resourceType === 'Observation');
+    const provenance = resources.filter((resource) => resource.resourceType === 'Provenance');
+    if (observations.length === 0)
+        throw new Error('Connected Device bundle requires at least one Observation.');
+    if (provenance.length === 0)
+        throw new Error('Connected Device bundle requires Provenance.');
+    const subjectIdentifier = readIdentifierValue(patient, options.expectedSubjectIdentifier, options.expectedSubjectIdentifierSystem);
+    if (subjectIdentifier !== options.expectedSubjectIdentifier) {
+        throw new Error('FHIR Patient does not identify the exact authorized subject identifier.');
+    }
+    const hasAnimalExtension = (patient.extension || [])
+        .some((extension) => extension.url === FHIR_R4_PATIENT_ANIMAL_EXTENSION_URL);
+    if ((options.expectedSubjectKind === 'animal') !== hasAnimalExtension) {
+        throw new Error(`FHIR Patient subject kind does not match ${options.expectedSubjectKind}.`);
+    }
+    const patientReference = `Patient/${requiredResourceId(patient)}`;
+    const deviceReference = `Device/${requiredResourceId(device)}`;
+    if (referenceValue(device.patient) !== patientReference) {
+        throw new Error('Device.patient must reference the exact FHIR Patient projection.');
+    }
+    readFirstIdentifier(device, 'Device');
+    const provenanceTargets = new Set(provenance.flatMap((resource) => (resource.target || []).map((target) => String(target.reference || '').trim())));
+    for (const resource of provenance) {
+        const agents = resource.agent || [];
+        if (!agents.some((agent) => agent.who?.reference || agent.who?.identifier)) {
+            throw new Error('Provenance requires an accountable agent.');
+        }
+    }
+    const normalizedObservations = observations.map((observation) => {
+        const observationReference = `Observation/${requiredResourceId(observation)}`;
+        if (!provenanceTargets.has(observationReference)) {
+            throw new Error(`Provenance does not cover ${observationReference}.`);
+        }
+        validateObservation(observation, patientReference, deviceReference);
+        return { resource: observation, claims: scalarClaims(observationToFlatFhirR4(observation)) };
+    });
+    return {
+        subjectIdentifier,
+        subjectKind: options.expectedSubjectKind,
+        device: { resource: device, claims: scalarClaims(deviceFhirR4ToFlat(device)) },
+        observations: normalizedObservations,
+        provenance,
+        sourceBundle: bundle,
+    };
+}
+function buildObservation(input, patientReference, deviceReference, organizationReference) {
+    assertId(input.id, 'observation.id');
+    if (!input.identifierSystem.trim() || !input.identifierValue.trim())
+        throw new Error('Observation identifier is required.');
+    if (!input.codeSystem.trim() || !input.code.trim())
+        throw new Error('Observation code system and code are required.');
+    if (!Number.isFinite(input.value))
+        throw new Error('Observation numeric value must be finite.');
+    if (!Number.isFinite(Date.parse(input.effectiveDateTime)))
+        throw new Error('Observation effectiveDateTime must be ISO 8601.');
+    return {
+        resourceType: 'Observation',
+        id: input.id,
+        identifier: [{ system: input.identifierSystem, value: input.identifierValue }],
+        status: input.status,
+        category: [{ coding: [{ system: 'http://terminology.hl7.org/CodeSystem/observation-category', code: 'vital-signs' }] }],
+        code: { coding: [{ system: input.codeSystem, code: input.code, ...(input.display ? { display: input.display } : {}) }] },
+        subject: { reference: patientReference },
+        device: { reference: deviceReference },
+        performer: [{ reference: organizationReference }],
+        effectiveDateTime: input.effectiveDateTime,
+        valueQuantity: {
+            value: input.value,
+            unit: input.unit,
+            system: input.unitSystem,
+            code: input.unitCode,
+        },
+    };
+}
+function validateObservation(resource, patientReference, deviceReference) {
+    readFirstIdentifier(resource, 'Observation');
+    if (referenceValue(resource.subject) !== patientReference)
+        throw new Error('Observation.subject does not match the exact Patient.');
+    if (referenceValue(resource.device) !== deviceReference)
+        throw new Error('Observation.device does not match the registered Device.');
+    const coding = resource.code?.coding?.[0];
+    if (!coding?.system || !coding.code)
+        throw new Error('Observation requires a coded measurement.');
+    if (!resource.effectiveDateTime && !resource.issued)
+        throw new Error('Observation requires an effective or issued time.');
+    if (!resource.valueQuantity && !resource.valueCodeableConcept && resource.valueString === undefined) {
+        throw new Error('Observation requires a value.');
+    }
+}
+function requireExactlyOne(resources, resourceType) {
+    const matches = resources.filter((resource) => resource.resourceType === resourceType);
+    if (matches.length !== 1)
+        throw new Error(`Connected Device bundle requires exactly one ${resourceType}.`);
+    return matches[0];
+}
+function readIdentifierValue(resource, expected, expectedSystem) {
+    const identifiers = resource.identifier || [];
+    return String(identifiers.find((identifier) => identifier.system === expectedSystem && identifier.value === expected)?.value || '');
+}
+function readFirstIdentifier(resource, label) {
+    const value = String(resource.identifier?.[0]?.value || '').trim();
+    if (!value)
+        throw new Error(`${label} requires a stable identifier for replay protection.`);
+    return value;
+}
+function requiredResourceId(resource) {
+    const id = String(resource.id || '').trim();
+    assertId(id, `${resource.resourceType}.id`);
+    return id;
+}
+function referenceValue(value) {
+    return String(value?.reference || '').trim();
+}
+function scalarClaims(claims) {
+    return Object.freeze(Object.fromEntries(Object.entries(claims)
+        .filter((entry) => entry[1] !== undefined)
+        .map(([key, value]) => [key, String(value)])));
+}
+function assertStableIdentifier(value, field) {
+    if (!/^(?:did|urn|https):\S+$/i.test(String(value || '').trim()))
+        throw new Error(`${field} must be a stable URI.`);
+}
+function assertReference(value, field) {
+    if (!/^[A-Z][A-Za-z]+\/[A-Za-z0-9.-]+$/.test(String(value || '').trim()))
+        throw new Error(`${field} must be a FHIR reference.`);
+}
+function assertId(value, field) {
+    if (!/^[A-Za-z0-9.-]{1,64}$/.test(String(value || '').trim()))
+        throw new Error(`${field} must be a valid FHIR id.`);
+}

package/dist/utils/did.d.ts

@@ -36,7 +36,10 @@ export declare function generateServiceId(selector: ServiceEndpointSelector): st
  * due to case sensitivity in the path component of the underlying URL.
  *
  * The rule is:
- * - All segments are lowercased, EXCEPT the final segment.
+ * - The DNS authority and ordinary non-final path segments are lowercased.
+ * - A hosted VAT tenant segment is uppercased (`vates-b...` -> `VATES-B...`).
+ * - A `cds-<jurisdiction>` segment uses an uppercase ISO jurisdiction.
+ * - The final segment is preserved.
  * - If the final segment represents a `system|code` pair (e.g., for a role),
  *   the `system` part is lowercased, but the `code` is preserved as-is.
  * - If the final segment is a unique identifier (like a Tax ID), it is preserved as-is.

package/dist/utils/did.js

@@ -56,7 +56,10 @@ export function generateServiceId(selector) {
  * due to case sensitivity in the path component of the underlying URL.
  *
  * The rule is:
- * - All segments are lowercased, EXCEPT the final segment.
+ * - The DNS authority and ordinary non-final path segments are lowercased.
+ * - A hosted VAT tenant segment is uppercased (`vates-b...` -> `VATES-B...`).
+ * - A `cds-<jurisdiction>` segment uses an uppercase ISO jurisdiction.
+ * - The final segment is preserved.
  * - If the final segment represents a `system|code` pair (e.g., for a role),
  *   the `system` part is lowercased, but the `code` is preserved as-is.
  * - If the final segment is a unique identifier (like a Tax ID), it is preserved as-is.
@@ -70,16 +73,30 @@ export function normalizeDidWeb(did) {
         // Not a valid did:web, return as is.
         return did;
     }
-    // Lowercase all parts except the very last one.
-    const lowercasedParts = parts.slice(0, -1).map(part => part.toLowerCase());
-    let lastPart = parts[parts.length - 1];
-    // Special handling for the last part if it contains a role descriptor.
-    if (lastPart.includes('|')) {
-        const [system, ...codeParts] = lastPart.split('|');
-        const code = codeParts.join('|'); // Re-join in case the code itself has a pipe.
-        lastPart = `${system.toLowerCase()}|${code}`;
-    }
-    return [...lowercasedParts, lastPart].join(':');
+    const lastIndex = parts.length - 1;
+    return parts.map((part, index) => {
+        if (index < 2)
+            return part.toLowerCase();
+        if (index === 2)
+            return part.toLowerCase().replace(/%3a/gi, '%3A');
+        // Hosted tenant identifiers use the canonical VAT + ISO country prefix.
+        // Keep this deliberately narrow so unrelated opaque DID path identifiers
+        // are not modified merely because they contain the letters "vat".
+        if (/^vat[a-z]{2}[-a-z0-9._]+$/i.test(part)) {
+            return part.toUpperCase();
+        }
+        const jurisdictionMatch = /^cds-([a-z]{2})$/i.exec(part);
+        if (jurisdictionMatch) {
+            return `cds-${jurisdictionMatch[1].toUpperCase()}`;
+        }
+        if (index === lastIndex) {
+            if (!part.includes('|'))
+                return part;
+            const [system, ...codeParts] = part.split('|');
+            return `${system.toLowerCase()}|${codeParts.join('|')}`;
+        }
+        return part.toLowerCase();
+    }).join(':');
 }
 /**
 * Encodes a hostname according to did:web spec (percent-encodes port colons).

package/dist/utils/index.d.ts

@@ -106,6 +106,7 @@ export * from './smart-scope';
 export * from './service-act-reasons';
 export * from './same-as';
 export * from './subject-identity';
+export * from './connected-device-fhir-r4';
 export * from './subject-identity-binding';
 export * from './activation-request';
 export * from './actor-identifier';

package/dist/utils/index.js

@@ -106,6 +106,7 @@ export * from './smart-scope.js';
 export * from './service-act-reasons.js';
 export * from './same-as.js';
 export * from './subject-identity.js';
+export * from './connected-device-fhir-r4.js';
 export * from './subject-identity-binding.js';
 export * from './activation-request.js';
 export * from './actor-identifier.js';

package/dist/utils/license-list-search.js

@@ -139,6 +139,35 @@ function extractClaims(entry) {
     const resourceClaims = resourceMeta.claims && typeof resourceMeta.claims === 'object' ? resourceMeta.claims : undefined;
     return { ...(resourceClaims || {}), ...(metaClaims || {}) };
 }
+function isLicenseListEntry(entry) {
+    const meta = entry.meta && typeof entry.meta === 'object'
+        ? entry.meta
+        : {};
+    const claims = extractClaims(entry);
+    return !!(normalizeText(meta.status)
+        || normalizeText(entry.status)
+        || normalizeText(entry.id)
+        || normalizeText(claims[ClaimsIndividualProductSchemaorg.serialNumber])
+        || normalizeText(claims[ClaimsOfferSchemaorg.serialNumber]));
+}
+function extractLicenseListEntries(node) {
+    if (!node || typeof node !== 'object')
+        return [];
+    if (Array.isArray(node)) {
+        return node.flatMap((entry) => extractLicenseListEntries(entry));
+    }
+    const entry = node;
+    const resource = entry.resource && typeof entry.resource === 'object'
+        ? entry.resource
+        : undefined;
+    if (resource && Array.isArray(resource.data)) {
+        return extractLicenseListEntries(resource.data);
+    }
+    if (Array.isArray(entry.data)) {
+        return extractLicenseListEntries(entry.data);
+    }
+    return isLicenseListEntry(entry) ? [entry] : [];
+}
 /**
  * Reads license-like search/list records from one current GW-style response
  * body without exposing raw claim access to frontend code.
@@ -146,7 +175,7 @@ function extractClaims(entry) {
 export function readLicenseListRecords(body) {
     const root = body && typeof body === 'object' ? body : {};
     const bodyNode = root.body && typeof root.body === 'object' ? root.body : root;
-    const data = Array.isArray(bodyNode.data) ? bodyNode.data : [];
+    const data = extractLicenseListEntries(bodyNode);
     return data
         .filter((entry) => !!entry && typeof entry === 'object')
         .map((entry) => {
@@ -156,9 +185,9 @@ export function readLicenseListRecords(body) {
             id: normalizeText(claims[ClaimsIndividualProductSchemaorg.serialNumber]
                 || claims[ClaimsOfferSchemaorg.serialNumber]
                 || entry.id),
-            status: normalizeText(meta.status),
-            subjectId: normalizeText(meta.subjectId),
-            ownerOrganizationId: normalizeText(meta.ownerOrganizationId || claims['License.ownerOrganizationId']),
+            status: normalizeText(meta.status || entry.status),
+            subjectId: normalizeText(meta.subjectId || entry.subjectId),
+            ownerOrganizationId: normalizeText(meta.ownerOrganizationId || entry.ownerOrganizationId || claims['License.ownerOrganizationId']),
             email: normalizeText(claims[ClaimsPersonSchemaorg.email]),
             telephone: normalizeText(claims[ClaimsPersonSchemaorg.telephone]),
             role: normalizeText(claims[ClaimsPersonSchemaorg.hasOccupationalRoleValue]),

package/dist/utils/medication-statement-entry-editor.d.ts

@@ -31,15 +31,19 @@ export declare class MedicationStatementEntryEditor extends ClinicalResourceEntr
     setEffective(value?: string | null): this;
     /** Returns the effective date or period token. */
     getEffective(): string | undefined;
-    /** Sets the coded medication identifier/value used by downstream FHIR export. */
+    /** Sets the official `code` token SearchParameter value for `medication.concept`. */
     setCode(code?: string | null): this;
-    /** Returns the coded medication identifier/value. */
+    /** Returns the official `code` token SearchParameter value. */
     getCode(): string | undefined;
-    /** Sets the human-readable medication text shown in UI cards and document narratives. */
+    /** Sets the official `medication` reference SearchParameter value for `medication.reference`. */
+    setMedication(reference?: string | null): this;
+    /** Returns the official `medication` reference SearchParameter value. */
+    getMedication(): string | undefined;
+    /** @deprecated Prefer `setCodeTextLocal`; this compatibility method now emits canonical `code-text`. */
     setMedicationText(text?: string | null): this;
-    /** Returns the human-readable medication text. */
+    /** Returns canonical `code-text`, falling back to historical `medication-text`. */
     getMedicationText(): string | undefined;
-    /** Alias used consistently by coded IPS editors for local FHIR text. */
+    /** Sets local/manual `medication.concept.text` as canonical `code-text`. */
     setCodeTextLocal(text?: string | null): this;
     /** Returns the local-language medication text. */
     getCodeTextLocal(): string | undefined;
@@ -47,6 +51,22 @@ export declare class MedicationStatementEntryEditor extends ClinicalResourceEntr
     setCodeDisplay(display?: string | null): this;
     /** Returns the English/international terminology display. */
     getCodeDisplay(): string | undefined;
+    /** Sets the official R5 `adherence` token; the dotted HL7 FHIRPath is never emitted as a claim key. */
+    setAdherence(value?: string | null): this;
+    /** Returns the official R5 `adherence` token SearchParameter value. */
+    getAdherence(): string | undefined;
+    /** Convenience alias that emits the official R5 `adherence` SearchParameter claim. */
+    setAdherenceCode(value?: string | null): this;
+    /** Convenience alias that reads the official R5 `adherence` SearchParameter claim. */
+    getAdherenceCode(): string | undefined;
+    /** Sets local/manual text for the R5 adherence CodeableConcept. */
+    setAdherenceCodeTextLocal(value?: string | null): this;
+    /** Returns local/manual text for the R5 adherence CodeableConcept. */
+    getAdherenceCodeTextLocal(): string | undefined;
+    /** Sets the terminology display for the R5 adherence Coding. */
+    setAdherenceCodeDisplay(value?: string | null): this;
+    /** Returns the terminology display for the R5 adherence Coding. */
+    getAdherenceCodeDisplay(): string | undefined;
     /** Sets one free-text note attached to the medication entry. */
     setNote(note?: string | null): this;
     /** Returns the current medication note. */

package/dist/utils/medication-statement-entry-editor.js

@@ -34,22 +34,45 @@ export class MedicationStatementEntryEditor extends ClinicalResourceEntryEditor
     setEffective(value) { return this.setScalarClaim(MedicationStatementClaim.Effective, value); }
     /** Returns the effective date or period token. */
     getEffective() { return this.getScalarClaim(MedicationStatementClaim.Effective); }
-    /** Sets the coded medication identifier/value used by downstream FHIR export. */
+    /** Sets the official `code` token SearchParameter value for `medication.concept`. */
     setCode(code) { return this.setScalarClaim(MedicationStatementClaim.Code, code); }
-    /** Returns the coded medication identifier/value. */
+    /** Returns the official `code` token SearchParameter value. */
     getCode() { return this.getScalarClaim(MedicationStatementClaim.Code); }
-    /** Sets the human-readable medication text shown in UI cards and document narratives. */
-    setMedicationText(text) { return this.setScalarClaim(MedicationStatementClaim.MedicationText, text); }
-    /** Returns the human-readable medication text. */
-    getMedicationText() { return this.getScalarClaim(MedicationStatementClaim.MedicationText); }
-    /** Alias used consistently by coded IPS editors for local FHIR text. */
-    setCodeTextLocal(text) { return this.setMedicationText(text); }
+    /** Sets the official `medication` reference SearchParameter value for `medication.reference`. */
+    setMedication(reference) { return this.setScalarClaim(MedicationStatementClaim.Medication, reference); }
+    /** Returns the official `medication` reference SearchParameter value. */
+    getMedication() { return this.getScalarClaim(MedicationStatementClaim.Medication); }
+    /** @deprecated Prefer `setCodeTextLocal`; this compatibility method now emits canonical `code-text`. */
+    setMedicationText(text) { return this.setCodeTextLocal(text); }
+    /** Returns canonical `code-text`, falling back to historical `medication-text`. */
+    getMedicationText() { return this.getCodeTextLocal(); }
+    /** Sets local/manual `medication.concept.text` as canonical `code-text`. */
+    setCodeTextLocal(text) { return this.setScalarClaim(MedicationStatementClaim.CodeText, text); }
     /** Returns the local-language medication text. */
-    getCodeTextLocal() { return this.getMedicationText(); }
+    getCodeTextLocal() {
+        return this.getScalarClaim(MedicationStatementClaim.CodeText)
+            || this.getScalarClaim(MedicationStatementClaim.MedicationText);
+    }
     /** Sets the English/international terminology display. */
     setCodeDisplay(display) { return this.setScalarClaim(MedicationStatementClaim.CodeDisplay, display); }
     /** Returns the English/international terminology display. */
     getCodeDisplay() { return this.getScalarClaim(MedicationStatementClaim.CodeDisplay); }
+    /** Sets the official R5 `adherence` token; the dotted HL7 FHIRPath is never emitted as a claim key. */
+    setAdherence(value) { return this.setScalarClaim(MedicationStatementClaim.Adherence, value); }
+    /** Returns the official R5 `adherence` token SearchParameter value. */
+    getAdherence() { return this.getScalarClaim(MedicationStatementClaim.Adherence); }
+    /** Convenience alias that emits the official R5 `adherence` SearchParameter claim. */
+    setAdherenceCode(value) { return this.setAdherence(value); }
+    /** Convenience alias that reads the official R5 `adherence` SearchParameter claim. */
+    getAdherenceCode() { return this.getAdherence(); }
+    /** Sets local/manual text for the R5 adherence CodeableConcept. */
+    setAdherenceCodeTextLocal(value) { return this.setScalarClaim(MedicationStatementClaim.AdherenceText, value); }
+    /** Returns local/manual text for the R5 adherence CodeableConcept. */
+    getAdherenceCodeTextLocal() { return this.getScalarClaim(MedicationStatementClaim.AdherenceText); }
+    /** Sets the terminology display for the R5 adherence Coding. */
+    setAdherenceCodeDisplay(value) { return this.setScalarClaim(MedicationStatementClaim.AdherenceDisplay, value); }
+    /** Returns the terminology display for the R5 adherence Coding. */
+    getAdherenceCodeDisplay() { return this.getScalarClaim(MedicationStatementClaim.AdherenceDisplay); }
     /** Sets one free-text note attached to the medication entry. */
     setNote(note) { return this.setScalarClaim(MedicationStatementClaim.Note, note); }
     /** Returns the current medication note. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.5.8",
+  "version": "2.5.10",
   "publishConfig": {
     "access": "public"
   },