fhir-data-utils-ts 0.3.1 → 0.3.3

package/.codex/skills/preserve-fhir-flat-coding-review/SKILL.md

@@ -19,6 +19,12 @@ redeclare governed claim paths, code systems, UUIDs or example values.
 - Each proposal `field` names the coded target claim. Confirmation writes
   `system|code` to that target and the terminology display to `-display`; it
   must preserve the imported `-text` value.
+- Review state comes only from `meta.codingProposals[].status`. An accepted
+  professional decision sets that proposal's `userSelected=true`; never use
+  `userSelected` as a draft or promotion flag.
+- Group review UI with the package-owned clinical families: allergies and
+  intolerances, procedures, diagnostics and immunizations. Do not duplicate
+  resource-type lists in Vet, UHC or DataConv consumers.
 - A localized generated label may use a language-qualified `-text_<BCP47>`
   companion. It must not overwrite the imported local text before explicit
   review.
@@ -28,6 +34,12 @@ redeclare governed claim paths, code systems, UUIDs or example values.
   `entry[].data[]`.
 - Multiple imported rows may resolve to one stable UUID ResearchSubject. Keep
   every proposal on the clinical resource generated from its source row.
+- Complete each ResearchSubject independently when all of its own mandatory
+  proposals are resolved. Other subjects in the same import thread never block
+  it, and review always resumes from persisted resources without re-upload.
+- Text supplied by an individual, a source table or an automated/device flow
+  may create proposals, but does not mark an inferred code professionally
+  reviewed. Preserve origin/provenance separately from the review decision.
 
 ## Workflow
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.3 - 2026-09-23
+
+- Define product-neutral coding-review families and pending-proposal helpers.
+- Keep review workflow in `meta.codingProposals[].status`; reserve
+  `userSelected=true` for a code explicitly selected by a reviewer.
+
+## 0.3.2 - 2026-09-23
+
+- Preserve every coding identity from repeatable AllergyIntolerance and
+  MedicationStatement CodeableConcepts instead of retaining only `coding[0]`.
+- Keep the MedicationStatement dose quantity's human `unit` separate from its
+  coded `system|code`, with read compatibility for records written by 0.3.1.
+- Add executable regressions using the exact allergy and medication examples
+  from the HL7 IPS all-sections Bundle.
+
 ## 0.3.1 - 2026-09-21
 
 - Separate canonical claim catalogs from graph builders and move Immunization

package/README.md

@@ -55,6 +55,14 @@ Use `fhir-data-utils-ts/claims`, `/converters`, `/fhir-bundle`,
 `/fhir-search-parameters`, `/clinical-terminology`, `/group-r5` or
 `/research-study-r5` as appropriate.
 
+Repeatable `CodeableConcept.coding[]` identities are serialized in the owning
+token claim as a comma-separated list of complete `system|code` tokens. The
+first `*-display` remains source evidence for compatibility; authoritative
+labels for every coding are resolved from each token at the terminology
+boundary. FHIR `Quantity.unit` remains separate from its coded identity:
+MedicationStatement dosage uses `dose-quantity-unit` for the human unit and
+`dose-quantity` for `system|code`.
+
 ## Observation components
 
 Composite observations use a claims-first resource graph. The primary
@@ -109,3 +117,15 @@ claim strings, terminology identifiers, codes or UUIDs.
 coverage over converters, builders and core FHIR utilities. The package also
 tests every stable export subpath. Release validation additionally inspects the
 packed artifact and installs it in an isolated consumer before publication.
+# Coding-review workflow
+
+Imported wording remains in the resource's canonical `*-text` flat claim. Each
+unconfirmed terminology suggestion lives beside `meta.claims` in the owning
+contained resource's `meta.codingProposals[]`; it is never moved to
+`ResearchSubject.meta`.
+
+Review state comes only from `codingProposals[].status`. A Coding
+`userSelected=true` flat claim records that a human selected the accepted code;
+it is not a draft, publication or promotion flag. Consumers can use the shared
+review families `allergies-intolerances`, `procedures`, `diagnostics` and
+`immunizations` without product-specific literals.

package/dist/coding-review-flat-claims.d.ts

@@ -13,6 +13,7 @@ export type FlatClaimCodingProposal = Readonly<{
     language: string;
     candidates: readonly FlatClaimCodingCandidate[];
     selectedCandidateId?: string;
+    userSelected?: boolean;
 }>;
 export type FlatClaimCodingReviewResource = Readonly<{
     resourceType: string;
@@ -43,6 +44,18 @@ export type ContainedCodingReviewItem = Readonly<{
     resource: FlatClaimCodingReviewResource;
     proposal: FlatClaimCodingProposal;
 }>;
+export declare const CODING_REVIEW_CATEGORIES: Readonly<{
+    readonly AllergiesIntolerances: "allergies-intolerances";
+    readonly Procedures: "procedures";
+    readonly Diagnostics: "diagnostics";
+    readonly Immunizations: "immunizations";
+    readonly Other: "other";
+}>;
+export type CodingReviewCategory = typeof CODING_REVIEW_CATEGORIES[keyof typeof CODING_REVIEW_CATEGORIES];
+/** Map a FHIR resource type to its stable, product-neutral coding-review family. */
+export declare function codingReviewCategoryForResourceType(resourceType: string): CodingReviewCategory;
+/** A proposal remains reviewable until a reviewer accepts, rejects or defers it. */
+export declare function isCodingProposalPending(proposal: FlatClaimCodingProposal): boolean;
 /** Return the canonical local-text companion for a code-like flat claim. */
 export declare function deriveCodingLocalTextClaim(targetClaim: string): string;
 /** Return the official-display companion for a code-like flat claim. */
@@ -66,6 +79,8 @@ export declare function buildFlatClaimCodingReviewResource(input: Readonly<{
 }>): FlatClaimCodingReviewResource;
 /** Traverse every ResearchSubject entry and return resource-scoped proposals. */
 export declare function collectBatchCodingReviewItems(batch: FhirLikeCodingReviewBatch): readonly ContainedCodingReviewItem[];
+/** Return only unresolved contained-resource proposals; resource userSelected is not workflow state. */
+export declare function collectPendingBatchCodingReviewItems(batch: FhirLikeCodingReviewBatch): readonly ContainedCodingReviewItem[];
 /**
  * Confirm one terminology candidate on the resource that owns the proposal.
  * The coded claim and official display are added while the imported local

package/dist/coding-review-flat-claims.js

@@ -1,4 +1,27 @@
 import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+export const CODING_REVIEW_CATEGORIES = Object.freeze({
+    AllergiesIntolerances: 'allergies-intolerances',
+    Procedures: 'procedures',
+    Diagnostics: 'diagnostics',
+    Immunizations: 'immunizations',
+    Other: 'other',
+});
+const CODING_REVIEW_RESOURCE_CATEGORIES = Object.freeze({
+    AllergyIntolerance: CODING_REVIEW_CATEGORIES.AllergiesIntolerances,
+    Procedure: CODING_REVIEW_CATEGORIES.Procedures,
+    Condition: CODING_REVIEW_CATEGORIES.Diagnostics,
+    DiagnosticReport: CODING_REVIEW_CATEGORIES.Diagnostics,
+    Observation: CODING_REVIEW_CATEGORIES.Diagnostics,
+    Immunization: CODING_REVIEW_CATEGORIES.Immunizations,
+});
+/** Map a FHIR resource type to its stable, product-neutral coding-review family. */
+export function codingReviewCategoryForResourceType(resourceType) {
+    return CODING_REVIEW_RESOURCE_CATEGORIES[resourceType] ?? CODING_REVIEW_CATEGORIES.Other;
+}
+/** A proposal remains reviewable until a reviewer accepts, rejects or defers it. */
+export function isCodingProposalPending(proposal) {
+    return proposal.status === 'proposed';
+}
 /** Return the canonical local-text companion for a code-like flat claim. */
 export function deriveCodingLocalTextClaim(targetClaim) {
     return `${requiredCodingTarget(targetClaim)}-text`;
@@ -54,6 +77,10 @@ export function collectBatchCodingReviewItems(batch) {
     }
     return Object.freeze(items);
 }
+/** Return only unresolved contained-resource proposals; resource userSelected is not workflow state. */
+export function collectPendingBatchCodingReviewItems(batch) {
+    return Object.freeze(collectBatchCodingReviewItems(batch).filter(item => isCodingProposalPending(item.proposal)));
+}
 /**
  * Confirm one terminology candidate on the resource that owns the proposal.
  * The coded claim and official display are added while the imported local
@@ -72,6 +99,7 @@ export function applyFlatClaimCodingSelection(resource, proposalId, candidateId)
         ...proposal,
         status: 'accepted',
         selectedCandidateId: candidate.id,
+        userSelected: true,
     });
     const updatedProposals = proposals.map((item, index) => (index === proposalIndex ? updatedProposal : item));
     return Object.freeze({
@@ -81,6 +109,7 @@ export function applyFlatClaimCodingSelection(resource, proposalId, candidateId)
                 ...resource.meta.claims,
                 [proposal.field]: `${candidate.system}|${candidate.code}`,
                 [deriveCodingDisplayClaim(proposal.field)]: candidate.display,
+                [`${resource.resourceType}.userSelected`]: 'true',
             }),
             codingProposals: Object.freeze(updatedProposals),
         }),
@@ -116,6 +145,7 @@ const CONDITION_EXPECTED_ACCEPTED_CLAIMS = Object.freeze({
     ...CONDITION_EXAMPLE_RESOURCE.meta.claims,
     [CONDITION_EXAMPLE_INPUT.targetClaim]: `${CONDITION_EXAMPLE_CANDIDATE.system}|${CONDITION_EXAMPLE_CANDIDATE.code}`,
     [deriveCodingDisplayClaim(CONDITION_EXAMPLE_INPUT.targetClaim)]: CONDITION_EXAMPLE_CANDIDATE.display,
+    [`${CONDITION_EXAMPLE_RESOURCE.resourceType}.userSelected`]: 'true',
 });
 /** Package-owned reusable fixture; tests and consumer examples must import it. */
 export const CODING_REVIEW_EXAMPLES = Object.freeze({

package/dist/converters/convert-allergy-intolerance.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/utils/convert-allergy-intolerance.ts
 import { AllergyIntoleranceClaim } from '../claims/allergy-intolerance-claims.js';
-import { codingFromValue, codingToValue, requireDidWeb, requireSubjectIdentifier } from './convert-shared.js';
+import { codingFromValue, codingListFromCsv, codingListToCsv, codingToValue, requireDidWeb, requireSubjectIdentifier, } from './convert-shared.js';
 export function allergyIntoleranceFlatToFhirR4(claims) {
     const patient = claims[AllergyIntoleranceClaim.Subject] ?? claims[AllergyIntoleranceClaim.Patient];
     const recorder = claims[AllergyIntoleranceClaim.Recorder];
@@ -23,9 +23,9 @@ export function allergyIntoleranceFlatToFhirR4(claims) {
         patient: { reference: patient },
         code: claims[AllergyIntoleranceClaim.Code]
             ? {
-                coding: codingFromValue(claims[AllergyIntoleranceClaim.Code])?.map((coding) => ({
+                coding: codingListFromCsv(claims[AllergyIntoleranceClaim.Code])?.map((coding, index) => ({
                     ...coding,
-                    ...(claims[AllergyIntoleranceClaim.CodeDisplay]
+                    ...(index === 0 && claims[AllergyIntoleranceClaim.CodeDisplay]
                         ? { display: claims[AllergyIntoleranceClaim.CodeDisplay] }
                         : {}),
                 })),
@@ -64,7 +64,7 @@ export function allergyIntoleranceFhirR4ToFlat(resource) {
         [AllergyIntoleranceClaim.Identifier]: resource.identifier?.[0]?.value,
         [AllergyIntoleranceClaim.Subject]: subject,
         [AllergyIntoleranceClaim.Patient]: subject,
-        [AllergyIntoleranceClaim.Code]: codingToValue(code?.coding?.[0]) || code?.text,
+        [AllergyIntoleranceClaim.Code]: codingListToCsv(code?.coding) || code?.text,
         [AllergyIntoleranceClaim.CodeText]: code?.text,
         [AllergyIntoleranceClaim.CodeDisplay]: code?.coding?.[0]?.display,
         [AllergyIntoleranceClaim.ClinicalStatus]: resource.clinicalStatus?.coding?.[0]?.code,

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

@@ -1,7 +1,18 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/utils/convert-medication-statement.ts
-import { MedicationStatementClaim } from '../claims/medication-statement-claims.js';
-import { codingFromValue, codingToValue, requireClaim } from './convert-shared.js';
+import { MedicationStatementClaim, MedicationStatementClaimsFhirApiExtended, } from '../claims/medication-statement-claims.js';
+import { codingFromValue, codingListFromCsv, codingListToCsv, codingToValue, requireClaim, } from './convert-shared.js';
+function isCodingToken(value) {
+    return Boolean(value?.includes('|'));
+}
+function conceptCodings(claims) {
+    return codingListFromCsv(claims[MedicationStatementClaim.Code])?.map((coding, index) => ({
+        ...coding,
+        ...(index === 0 && claims[MedicationStatementClaim.CodeDisplay]
+            ? { display: claims[MedicationStatementClaim.CodeDisplay] }
+            : {}),
+    }));
+}
 export function medicationStatementFlatToFhirR4(claims) {
     const subject = requireClaim(claims, MedicationStatementClaim.Subject);
     const status = requireClaim(claims, MedicationStatementClaim.Status);
@@ -24,10 +35,7 @@ export function medicationStatementFlatToFhirR4(claims) {
         id: containedMedicationId,
         identifier: medicationIdentifier ? [{ value: medicationIdentifier }] : undefined,
         code: claims[MedicationStatementClaim.Code] || medicationText ? {
-            coding: codingFromValue(claims[MedicationStatementClaim.Code])?.map((coding) => ({
-                ...coding,
-                ...(claims[MedicationStatementClaim.CodeDisplay] ? { display: claims[MedicationStatementClaim.CodeDisplay] } : {}),
-            })),
+            coding: conceptCodings(claims),
             ...(medicationText ? { text: medicationText } : {}),
         } : undefined,
         batch: medicationSerialNumber || medicationExpirationDate ? {
@@ -40,7 +48,10 @@ export function medicationStatementFlatToFhirR4(claims) {
     const dosagePeriod = claims[MedicationStatementClaim.TimingPeriod];
     const dosagePeriodUnit = claims[MedicationStatementClaim.TimingPeriodUnit];
     const doseValue = claims[MedicationStatementClaim.DoseQuantityValue];
-    const doseUnit = claims[MedicationStatementClaim.DoseQuantityUnit];
+    const storedDoseUnit = claims[MedicationStatementClaim.DoseQuantityUnit];
+    const doseUnitToken = claims[MedicationStatementClaimsFhirApiExtended.DoseQuantity]
+        || (isCodingToken(storedDoseUnit) ? storedDoseUnit : undefined);
+    const doseUnitText = isCodingToken(storedDoseUnit) ? undefined : storedDoseUnit;
     const hasDosage = claims[MedicationStatementClaim.DosageInstruction] || dosageRoute || dosageFrequency || dosagePeriod || doseValue;
     return {
         resourceType: 'MedicationStatement',
@@ -54,10 +65,7 @@ export function medicationStatementFlatToFhirR4(claims) {
         } : undefined,
         medicationCodeableConcept: !medicationReference && !hasContainedMedication && claims[MedicationStatementClaim.Code]
             ? {
-                coding: codingFromValue(claims[MedicationStatementClaim.Code])?.map((coding) => ({
-                    ...coding,
-                    ...(claims[MedicationStatementClaim.CodeDisplay] ? { display: claims[MedicationStatementClaim.CodeDisplay] } : {}),
-                })),
+                coding: conceptCodings(claims),
                 ...(medicationText ? { text: medicationText } : {}),
             }
             : (!medicationReference && !hasContainedMedication && medicationText ? { text: medicationText } : undefined),
@@ -76,8 +84,8 @@ export function medicationStatementFlatToFhirR4(claims) {
                     } } : undefined,
                 doseAndRate: doseValue ? [{ doseQuantity: {
                             value: Number(doseValue),
-                            unit: doseUnit,
-                            ...(codingFromValue(doseUnit)?.[0] || {}),
+                            ...(doseUnitText ? { unit: doseUnitText } : {}),
+                            ...(codingFromValue(doseUnitToken)?.[0] || {}),
                         } }] : undefined,
             }] : undefined,
         note: claims[MedicationStatementClaim.Note] ? [{ text: claims[MedicationStatementClaim.Note] }] : undefined,
@@ -94,7 +102,8 @@ export function medicationStatementFhirR4ToFlat(resource) {
     const containedMedicationText = containedMedicationConcept?.text;
     const batch = containedMedication?.batch;
     const medicationConcept = resource.medicationCodeableConcept;
-    const medicationCode = codingToValue(medicationConcept?.coding?.[0] || containedMedicationConcept?.coding?.[0]);
+    const medicationCodings = medicationConcept?.coding || containedMedicationConcept?.coding;
+    const medicationCode = codingListToCsv(medicationCodings);
     const medicationText = containedMedicationText || medicationConcept?.text || undefined;
     const dosage = resource.dosage?.[0];
     const repeat = dosage?.timing
@@ -119,7 +128,10 @@ export function medicationStatementFhirR4ToFlat(resource) {
         [MedicationStatementClaim.Source]: resource.informationSource?.reference,
         [MedicationStatementClaim.DosageRoute]: codingToValue(routeCoding),
         [MedicationStatementClaim.DoseQuantityValue]: doseQuantity?.value === undefined ? undefined : String(doseQuantity.value),
-        [MedicationStatementClaim.DoseQuantityUnit]: codingToValue(doseQuantity?.system || doseQuantity?.code ? { system: doseQuantity?.system, code: doseQuantity?.code } : undefined) || doseQuantity?.unit,
+        [MedicationStatementClaimsFhirApiExtended.DoseQuantity]: codingToValue(doseQuantity?.system || doseQuantity?.code
+            ? { system: doseQuantity?.system, code: doseQuantity?.code }
+            : undefined),
+        [MedicationStatementClaim.DoseQuantityUnit]: doseQuantity?.unit,
         [MedicationStatementClaim.TimingFrequency]: repeat?.frequency === undefined ? undefined : String(repeat.frequency),
         [MedicationStatementClaim.TimingPeriod]: repeat?.period === undefined ? undefined : String(repeat.period),
         [MedicationStatementClaim.TimingPeriodUnit]: repeat?.periodUnit,

package/dist/converters/convert-shared.d.ts

@@ -6,6 +6,11 @@ export declare function codingFromValue(value?: string): Array<{
     system?: string;
     code: string;
 }> | undefined;
+/** Convert one canonical comma-separated token list into FHIR Coding entries. */
+export declare function codingListFromCsv(value?: string): Array<{
+    system?: string;
+    code: string;
+}> | undefined;
 export declare function codingToValue(coding?: {
     system?: string;
     code?: string;

package/dist/converters/convert-shared.js

@@ -11,6 +11,15 @@ export function codingFromValue(value) {
         return [{ code: system }];
     return system ? [{ system, code }] : [{ code }];
 }
+/** Convert one canonical comma-separated token list into FHIR Coding entries. */
+export function codingListFromCsv(value) {
+    const codings = String(value || '')
+        .split(',')
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .flatMap((token) => codingFromValue(token) ?? []);
+    return codings.length ? codings : undefined;
+}
 export function codingToValue(coding) {
     if (!coding?.code)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",