fhir-data-utils-ts 0.3.2 → 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,11 @@
 # 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

package/README.md

@@ -117,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/package.json

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