fhir-data-utils-ts 0.2.3

package/.codex/skills/govern-fhir-observation-components/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: govern-fhir-observation-components
+description: Implement or audit neutral FHIR Observation claim catalogs, vital-sign terminology, component serialization, reduced component indexes, historical bp aliases, and R4/R5 projection adapters. Use when changing Observation.component, blood pressure, assessment scales, device readings, flat claims, portal or assistant vital-sign builders, or migrating code from gdc-common-utils-ts or uhc-fhir-utils-typescript.
+---
+
+# Govern FHIR Observation Components
+
+## Establish the boundary
+
+1. Treat native FHIR import/export as an adapter boundary. Keep flat claims as
+   the version-neutral internal contract.
+2. Read `src/observation-claims.ts`, `src/vital-sign-observations.ts`, their
+   tests, and `docs/UHC_FHIR_UTILS_MIGRATION.md` before changing behavior.
+3. Treat every `gdc-*` repository and `uhc-fhir-utils-typescript` as read-only
+   compatibility evidence unless the user explicitly changes that scope.
+4. Keep product policies in SOS, Vet or UHC packages. This package owns only
+   neutral FHIR data semantics.
+
+## Preserve the component contract
+
+- Model blood pressure as one native FHIR Observation with systolic and
+  diastolic `component[]` entries. Do not export those components as three
+  independent native Observations.
+- Encode aligned repeatable component claims with
+  `encodeObservationClaimList`. Emit JSON arrays because flat values are
+  strings and CSV is ambiguous for displays and text. Keep numeric component
+  values as strings inside those JSON arrays for compatibility with the
+  deployed flat-claim converter; parse numbers only at typed boundaries.
+- Accept historical CSV only through `decodeObservationClaimList`; never emit
+  it from a new writer.
+- Derive reduced component index entries generically by code, value and unit.
+  They carry their parent reference and ordinal, but no `Observation.status`
+  and no invented persistent identifier.
+- Never introduce scale-specific numeric claims. In particular,
+  `Observation.bp-systolic-number` and `Observation.bp-diastolic-number` are
+  read-only migration aliases. Apply the same rule to APGAR, Glasgow and other
+  composite observations.
+- Keep canonical component arrays on the parent as the reconstruction source.
+  A persistence adapter may preserve historical child identifiers or apply an
+  explicitly versioned identity policy; a neutral helper must not improvise
+  one.
+
+## Reuse governed names
+
+- Import every Observation claim key from `ObservationClaim`.
+- Import terminology from `ObservationCategoryCodes`, `VitalSignsCodes` and
+  `VitalSignsUnits`.
+- Let `buildVitalSignObservation` author canonical code/component displays and
+  the optional `Observation.user-selected` flag; consumers must not rebuild
+  those fields.
+- Add a missing neutral constant here once and consume it downstream. Do not
+  copy `Observation.*`, LOINC, UCUM or category strings into portals,
+  assistants, tests or snippets.
+- Keep displays separate from `system|code` tokens and local-language text.
+
+## Change with TDD
+
+1. Begin every new or modified test file with:
+   `// Flow contract: reuse shared test fixtures and canonical types; do not introduce duplicated literals.`
+2. Add the smallest failing test and retain its intended red result.
+3. Prove canonical JSON writing, legacy reading, generic indexing, absence of
+   `bp-*` output and one-Observation/two-component R4 and R5 projection.
+4. Add negative assertions against raw claim literals outside the owning
+   catalog and against invented persistent component identifiers.
+5. Run Node 24, `npm ci`, `npm run check` and `npm pack --dry-run`.
+
+## Promote consumers
+
+Release bottom-up. Publish this package first, install its exact registry
+version in the lowest consumer, and run that consumer's complete local matrix.
+Never commit `file:`, Git, workspace or tarball dependencies. Portals and
+assistants should call shared builders or use governed constants; they must not
+assemble component arrays with copied claim literals.
+
+Update JSDoc, high-level docs, tests, snippets and this skill together whenever
+the contract changes.

package/.codex/skills/govern-fhir-observation-components/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Govern FHIR Observation Components"
+  short_description: "Preserve canonical Observation component and index contracts"
+  default_prompt: "Use $govern-fhir-observation-components to implement or audit FHIR Observation flat claims, component indexes, vital signs, or R4/R5 projections without custom per-scale claims."

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

@@ -0,0 +1,57 @@
+---
+name: preserve-fhir-flat-coding-review
+description: Preserve the neutral flat-claim contract for imported local clinical text, terminology proposals and confirmed codings. Use when changing DataConv, Vet or UHC ingestion, ResearchSubject batches, contained clinical resources, coding-review UI/API contracts, examples, fixtures or tests.
+---
+
+# Preserve FHIR Flat Coding Review
+
+Keep imported local text, proposed terminology and confirmed coding as distinct
+states. Reuse the public builders and fixtures from `fhir-data-utils-ts`; do not
+redeclare governed claim paths, code systems, UUIDs or example values.
+
+## Canonical contract
+
+- Store source wording as the resource's canonical code-like local-text claim,
+  such as `<ResourceType>.<code-field>-text`. Never serialize `coding-input:*`.
+- Put `meta.codingProposals[]` on the same contained clinical resource as
+  `meta.claims`. Both are siblings. Never aggregate proposals into
+  `ResearchSubject.meta`.
+- 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.
+- A localized generated label may use a language-qualified `-text_<BCP47>`
+  companion. It must not overwrite the imported local text before explicit
+  review.
+- In a DIDComm-style batch, traverse
+  `body.data[].resource.contained[].meta.codingProposals[]`. In a native FHIR
+  Bundle projection, traverse `entry[].resource.contained[]`. Never invent
+  `entry[].data[]`.
+- Multiple imported rows may resolve to one stable UUID ResearchSubject. Keep
+  every proposal on the clinical resource generated from its source row.
+
+## Workflow
+
+1. Import `deriveCodingLocalTextClaim`, `deriveCodingDisplayClaim`,
+   `buildFlatClaimCodingReviewResource`, `applyFlatClaimCodingSelection` and
+   `CODING_REVIEW_EXAMPLES` from `fhir-data-utils-ts`.
+2. Write the smallest failing contract test first. Begin its suite with a flow
+   contract comment.
+3. Build the resource with source `-text` plus a resource-scoped proposal.
+4. Confirm a candidate only through the shared selection helper or an adapter
+   proven equivalent by contract tests.
+5. Test the real DataConv or product boundary, then update JSDoc, SYNC and
+   changelog together.
+6. Use local tarballs for the consumer matrix. Merge validated branches to
+   `main`, publish bottom-up, reinstall exact registry versions and only then
+   promote to staging.
+
+## Boundaries
+
+- This is FHIR-neutral shared data behavior. It belongs in
+  `fhir-data-utils-ts`, not SOSChain, Vet, UHC or frozen `gdc-*` packages.
+- DataConv applies the contract during import. Vet and UHC consume the same
+  contract and may add sector policy without forking its claim shape.
+- Do not put HTTP clients, gateway policy, product authorization or terminology
+  catalogs in this package.
+- Tests and examples import package-owned fixtures/builders. Do not scatter raw
+  claim names, code systems, codes, identifiers or UUIDs through consumers.

package/.codex/skills/preserve-fhir-flat-coding-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Preserve FHIR Flat Coding Review"
+  short_description: "Keep local text and coding proposals canonical"
+  default_prompt: "Use $preserve-fhir-flat-coding-review to implement or audit flat-claim coding review without duplicated literals."

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.2.3 - 2026-09-21
+
+- Preserve the deployed flat-claim component number wire contract by encoding
+  aligned numeric values as JSON string arrays while parsing them as numbers
+  at typed and native-FHIR boundaries.
+
+## 0.2.2 - 2026-09-21
+
+- Make the neutral vital-sign builder own canonical code displays, component
+  displays and the optional user-selected provenance claim so portals and
+  assistants no longer assemble those Observation fields from literals.
+
+## 0.2.1 - 2026-09-21
+
+- Add the repository skill that governs Observation component authoring,
+  compatibility, generic indexing, R4/R5 projection and consumer promotion.
+
+## 0.2.0 - 2026-09-21
+
+- Consolidate the canonical Observation claim names, vital-sign terminology,
+  JSON repeatable-component encoding, generic component index projection and
+  explicit R4/R5 projection boundary. Historical component CSV and `bp-*`
+  aliases remain read-only compatibility inputs.
+- Record the reuse/rewrite/retire audit of the original
+  `uhc-fhir-utils-typescript` architecture without adding its obsolete product,
+  transport, SHA-1, DICOM or build dependencies to the neutral package.
+- Add the neutral contained-resource coding-review contract: canonical imported
+  `*-text`, resource-scoped `meta.codingProposals[]`, batch traversal, candidate
+  confirmation and reusable governed fixtures for DataConv, Vet and UHC.
+- Add channel-neutral FHIR-like vital-sign Observation builders and lossless device-batch normalization while preserving device source without inventing professional attestation.
+- Introduce product-neutral flat-claim resource graphs, parent-owned
+  `contained-reference-list`, narrative `language`/`xhtml`, and governed
+  SearchParameter definitions.

package/README.md

@@ -0,0 +1,65 @@
+# fhir-data-utils-ts
+
+FHIR-neutral data contracts for flat claims, governed SearchParameter names,
+resource graphs and explicit R4/R5/R6 projection adapters. This package has no
+network clients and no dependency on GDC, SOS, Vet or UHC packages.
+
+Release order is local-first: local tarball consumers, complete local matrix,
+merge and push `main`, publish bottom-up, install exact registry versions, then
+staging. Never commit `file:`, Git or workspace dependencies.
+
+## Where this package sits
+
+```text
+fhir-data-utils-ts
+  └─ FHIR SearchParameters, flat-claim graphs and R4/R5/R6 projection rules
+      ↓
+sos-data-utils-ts
+  └─ cross-sector clinical catalogs and shared SOS/Vet/UHC data contracts
+      ├─ vet-data-utils-ts: animal species and veterinary policy
+      └─ uhc-data-utils-ts: human-health policy
+
+terminology-api-node-ts reads the neutral FHIR and shared SOS contracts.
+It never depends on Vet or UHC product packages.
+```
+
+FHIR resource graphs use independent entries. A parent links children only
+through `<ResourceType>.contained-reference-list`; children do not carry
+`is-contained` or `contained-parent-reference`. Narrative source is preserved
+as `<ResourceType>.language`, `.narrative-status` and `.xhtml`. Native FHIR is
+materialized only by an explicit R4/R5/R6 import or export adapter.
+
+## Observation components
+
+Repeatable `Observation.component[]` values are encoded as aligned JSON arrays
+inside string-valued flat claims. Historical CSV and blood-pressure `bp-*`
+aliases are read-only compatibility inputs. Generic reduced component rows may
+be derived for indexing, but they are not independent native FHIR resources
+and carry no top-level `Observation.status`.
+
+`buildVitalSignObservation` also owns canonical displays and the optional
+`Observation.user-selected` provenance flag. Consumers add their envelope and
+section context but do not reconstruct Observation component claims.
+
+See [the UHC FHIR utilities migration](docs/UHC_FHIR_UTILS_MIGRATION.md) for the
+reuse/rewrite/retire inventory and the rule for moving frozen contracts without
+changing any `gdc-*` repository.
+
+## Coding review for imported clinical text
+
+DataConv, Vet and UHC share one neutral review contract from
+`fhir-data-utils-ts/coding-review-flat-claims`:
+
+- imported wording is the canonical `<ResourceType>.<code-field>-text` claim;
+- `meta.codingProposals[]` is a sibling of `meta.claims` on that same contained
+  clinical resource, never on `ResearchSubject.meta`;
+- a proposal targets the coded claim, such as `Condition.code` or
+  `Immunization.vaccination-code`;
+- accepting a candidate adds `system|code` and the official `-display`, while
+  retaining the imported local `-text` value;
+- language-qualified generated local labels use `-text_<BCP47>` and do not
+  replace imported text until review explicitly chooses that operation.
+
+The package exports builders, traversal/confirmation helpers and
+`CODING_REVIEW_EXAMPLES`. Tests and consumers reuse them instead of duplicating
+claim strings, terminology identifiers, codes or UUIDs.

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

@@ -0,0 +1,134 @@
+export type FlatClaimCodingCandidate = Readonly<{
+    id: string;
+    system: string;
+    code: string;
+    display: string;
+    localText?: string;
+}>;
+export type FlatClaimCodingProposal = Readonly<{
+    id: string;
+    status: 'proposed' | 'accepted' | 'rejected' | 'deferred';
+    field: string;
+    inputText: string;
+    language: string;
+    candidates: readonly FlatClaimCodingCandidate[];
+    selectedCandidateId?: string;
+}>;
+export type FlatClaimCodingReviewResource = Readonly<{
+    resourceType: string;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+        codingProposals?: readonly FlatClaimCodingProposal[];
+    }>;
+}>;
+export type ResearchSubjectCodingReviewEntry = Readonly<{
+    resource: Readonly<{
+        resourceType: 'ResearchSubject';
+        id: string;
+        meta: Readonly<{
+            claims: Readonly<Record<string, string>>;
+            codingProposals?: never;
+        }>;
+        contained: readonly FlatClaimCodingReviewResource[];
+    }>;
+}>;
+export type FhirLikeCodingReviewBatch = Readonly<{
+    resourceType: 'Bundle';
+    type: 'batch';
+    data: readonly ResearchSubjectCodingReviewEntry[];
+}>;
+export type ContainedCodingReviewItem = Readonly<{
+    researchSubjectId: string;
+    resource: FlatClaimCodingReviewResource;
+    proposal: FlatClaimCodingProposal;
+}>;
+/** 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. */
+export declare function deriveCodingDisplayClaim(targetClaim: string): string;
+/**
+ * Build a reviewable contained resource.
+ *
+ * Imported wording remains the canonical local `*-text` flat claim. The
+ * proposal targets the code-like claim and is a sibling of `meta.claims`; it
+ * never becomes a claim and is never copied to ResearchSubject metadata.
+ */
+export declare function buildFlatClaimCodingReviewResource(input: Readonly<{
+    resourceType: string;
+    resourceId: string;
+    targetClaim: string;
+    localText: string;
+    language: string;
+    baseClaims: Readonly<Record<string, string>>;
+    proposalId: string;
+    candidates: readonly FlatClaimCodingCandidate[];
+}>): FlatClaimCodingReviewResource;
+/** Traverse every ResearchSubject entry and return resource-scoped proposals. */
+export declare function collectBatchCodingReviewItems(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
+ * `*-text` claim remains untouched for provenance and multilingual search.
+ */
+export declare function applyFlatClaimCodingSelection(resource: FlatClaimCodingReviewResource, proposalId: string, candidateId: string): FlatClaimCodingReviewResource;
+/** Package-owned reusable fixture; tests and consumer examples must import it. */
+export declare const CODING_REVIEW_EXAMPLES: Readonly<{
+    condition: Readonly<{
+        input: Readonly<{
+            resourceType: "Condition";
+            resourceId: "00000000-0000-4000-8000-000000000102";
+            targetClaim: "Condition.code";
+            localText: "otitis";
+            language: "es-ES";
+            baseClaims: Readonly<{
+                'Condition.identifier': "00000000-0000-4000-8000-000000000102";
+                'Condition.subject': "ResearchSubject/00000000-0000-4000-8000-000000000101";
+            }>;
+            proposalId: "condition-code-proposal-example";
+            candidates: readonly Readonly<{
+                id: "condition-candidate-example";
+                system: "http://snomed.info/sct";
+                code: "129127001";
+                display: "Otitis externa";
+            }>[];
+        }>;
+        resource: Readonly<{
+            resourceType: string;
+            id: string;
+            meta: Readonly<{
+                claims: Readonly<Record<string, string>>;
+                codingProposals?: readonly FlatClaimCodingProposal[];
+            }>;
+        }>;
+        expectedAcceptedClaims: Readonly<{
+            [x: string]: string;
+            "Condition.code": "http://snomed.info/sct|129127001";
+        }>;
+        expectedAcceptedProposalStatus: "accepted";
+    }>;
+    batch: Readonly<{
+        resourceType: "Bundle";
+        type: "batch";
+        data: readonly Readonly<{
+            resource: Readonly<{
+                resourceType: "ResearchSubject";
+                id: "00000000-0000-4000-8000-000000000101";
+                meta: Readonly<{
+                    claims: Readonly<{
+                        'ResearchSubject.identifier': "urn:uuid:00000000-0000-4000-8000-000000000101";
+                    }>;
+                }>;
+                contained: readonly Readonly<{
+                    resourceType: string;
+                    id: string;
+                    meta: Readonly<{
+                        claims: Readonly<Record<string, string>>;
+                        codingProposals?: readonly FlatClaimCodingProposal[];
+                    }>;
+                }>[];
+            }>;
+        }>[];
+    }>;
+    expectedReviewIdentities: readonly (readonly string[])[];
+}>;

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

@@ -0,0 +1,160 @@
+import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+/** Return the canonical local-text companion for a code-like flat claim. */
+export function deriveCodingLocalTextClaim(targetClaim) {
+    return `${requiredCodingTarget(targetClaim)}-text`;
+}
+/** Return the official-display companion for a code-like flat claim. */
+export function deriveCodingDisplayClaim(targetClaim) {
+    return `${requiredCodingTarget(targetClaim)}-display`;
+}
+/**
+ * Build a reviewable contained resource.
+ *
+ * Imported wording remains the canonical local `*-text` flat claim. The
+ * proposal targets the code-like claim and is a sibling of `meta.claims`; it
+ * never becomes a claim and is never copied to ResearchSubject metadata.
+ */
+export function buildFlatClaimCodingReviewResource(input) {
+    const targetClaim = requiredCodingTarget(input.targetClaim);
+    const prefix = `${input.resourceType}.`;
+    if (!targetClaim.startsWith(prefix))
+        throw new TypeError('coding_target_resource_type_mismatch');
+    const entry = buildFlatClaimResourceEntry({
+        entryId: input.resourceId,
+        resourceType: input.resourceType,
+        claims: {
+            ...input.baseClaims,
+            [deriveCodingLocalTextClaim(targetClaim)]: requiredText(input.localText, 'coding_local_text_required'),
+            [`${input.resourceType}.language`]: requiredText(input.language, 'coding_language_required'),
+        },
+    });
+    const proposal = Object.freeze({
+        id: requiredText(input.proposalId, 'coding_proposal_id_required'),
+        status: 'proposed',
+        field: targetClaim,
+        inputText: input.localText.trim(),
+        language: input.language.trim(),
+        candidates: Object.freeze(input.candidates.map(candidate => Object.freeze({ ...candidate }))),
+    });
+    return Object.freeze({
+        resourceType: entry.resourceType,
+        id: entry.entryId,
+        meta: Object.freeze({ claims: entry.claims, codingProposals: Object.freeze([proposal]) }),
+    });
+}
+/** Traverse every ResearchSubject entry and return resource-scoped proposals. */
+export function collectBatchCodingReviewItems(batch) {
+    const items = [];
+    for (const entry of batch.data) {
+        for (const resource of entry.resource.contained) {
+            for (const proposal of resource.meta.codingProposals ?? []) {
+                items.push(Object.freeze({ researchSubjectId: entry.resource.id, resource, proposal }));
+            }
+        }
+    }
+    return Object.freeze(items);
+}
+/**
+ * Confirm one terminology candidate on the resource that owns the proposal.
+ * The coded claim and official display are added while the imported local
+ * `*-text` claim remains untouched for provenance and multilingual search.
+ */
+export function applyFlatClaimCodingSelection(resource, proposalId, candidateId) {
+    const proposals = resource.meta.codingProposals ?? [];
+    const proposalIndex = proposals.findIndex(proposal => proposal.id === proposalId);
+    if (proposalIndex < 0)
+        throw new TypeError('coding_proposal_not_found');
+    const proposal = proposals[proposalIndex];
+    const candidate = proposal.candidates.find(item => item.id === candidateId);
+    if (!candidate)
+        throw new TypeError('coding_candidate_not_found');
+    const updatedProposal = Object.freeze({
+        ...proposal,
+        status: 'accepted',
+        selectedCandidateId: candidate.id,
+    });
+    const updatedProposals = proposals.map((item, index) => (index === proposalIndex ? updatedProposal : item));
+    return Object.freeze({
+        ...resource,
+        meta: Object.freeze({
+            claims: Object.freeze({
+                ...resource.meta.claims,
+                [proposal.field]: `${candidate.system}|${candidate.code}`,
+                [deriveCodingDisplayClaim(proposal.field)]: candidate.display,
+            }),
+            codingProposals: Object.freeze(updatedProposals),
+        }),
+    });
+}
+const RESEARCH_SUBJECT_EXAMPLE_ID = '00000000-0000-4000-8000-000000000101';
+const CONDITION_EXAMPLE_ID = '00000000-0000-4000-8000-000000000102';
+const CONDITION_PROPOSAL_EXAMPLE_ID = 'condition-code-proposal-example';
+const CONDITION_CANDIDATE_EXAMPLE_ID = 'condition-candidate-example';
+const CONDITION_EXAMPLE_INPUT = Object.freeze({
+    resourceType: 'Condition',
+    resourceId: CONDITION_EXAMPLE_ID,
+    targetClaim: 'Condition.code',
+    localText: 'otitis',
+    language: 'es-ES',
+    baseClaims: Object.freeze({
+        'Condition.identifier': CONDITION_EXAMPLE_ID,
+        'Condition.subject': `ResearchSubject/${RESEARCH_SUBJECT_EXAMPLE_ID}`,
+    }),
+    proposalId: CONDITION_PROPOSAL_EXAMPLE_ID,
+    candidates: Object.freeze([
+        Object.freeze({
+            id: CONDITION_CANDIDATE_EXAMPLE_ID,
+            system: 'http://snomed.info/sct',
+            code: '129127001',
+            display: 'Otitis externa',
+        }),
+    ]),
+});
+const CONDITION_EXAMPLE_RESOURCE = buildFlatClaimCodingReviewResource(CONDITION_EXAMPLE_INPUT);
+const CONDITION_EXAMPLE_CANDIDATE = CONDITION_EXAMPLE_INPUT.candidates[0];
+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,
+});
+/** Package-owned reusable fixture; tests and consumer examples must import it. */
+export const CODING_REVIEW_EXAMPLES = Object.freeze({
+    condition: Object.freeze({
+        input: CONDITION_EXAMPLE_INPUT,
+        resource: CONDITION_EXAMPLE_RESOURCE,
+        expectedAcceptedClaims: CONDITION_EXPECTED_ACCEPTED_CLAIMS,
+        expectedAcceptedProposalStatus: 'accepted',
+    }),
+    batch: Object.freeze({
+        resourceType: 'Bundle',
+        type: 'batch',
+        data: Object.freeze([
+            Object.freeze({
+                resource: Object.freeze({
+                    resourceType: 'ResearchSubject',
+                    id: RESEARCH_SUBJECT_EXAMPLE_ID,
+                    meta: Object.freeze({
+                        claims: Object.freeze({ 'ResearchSubject.identifier': `urn:uuid:${RESEARCH_SUBJECT_EXAMPLE_ID}` }),
+                    }),
+                    contained: Object.freeze([CONDITION_EXAMPLE_RESOURCE]),
+                }),
+            }),
+        ]),
+    }),
+    expectedReviewIdentities: Object.freeze([
+        Object.freeze([RESEARCH_SUBJECT_EXAMPLE_ID, CONDITION_EXAMPLE_ID, CONDITION_PROPOSAL_EXAMPLE_ID]),
+    ]),
+});
+function requiredCodingTarget(value) {
+    const target = requiredText(value, 'coding_target_claim_required');
+    if (!/^[A-Z][A-Za-z0-9]+\.(?:code|[a-z][a-z0-9-]*-code)$/.test(target)) {
+        throw new TypeError('coding_target_claim_invalid');
+    }
+    return target;
+}
+function requiredText(value, error) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/flat-claim-resource-graph.d.ts

@@ -0,0 +1,48 @@
+/** A canonical flat-claims resource entry; `entryId` is graph identity, never a business identifier. */
+export type FlatClaimResourceEntry = Readonly<{
+    entryId: string;
+    reference: string;
+    resourceType: string;
+    claims: Readonly<Record<string, string>>;
+}>;
+/** Version-neutral source for FHIR `Resource.language` and `DomainResource.text`. */
+export type FlatClaimNarrative = Readonly<{
+    language: string;
+    status: 'generated' | 'extensions' | 'additional' | 'empty';
+    xhtml: string;
+}>;
+/** Builds one independent resource entry whose claims all belong to its resource type. */
+export declare function buildFlatClaimResourceEntry(input: Readonly<{
+    entryId: string;
+    resourceType: string;
+    claims: Readonly<Record<string, string>>;
+}>): FlatClaimResourceEntry;
+/**
+ * Links contained or referenced resources from the parent flat entry.
+ *
+ * The comma-separated `<ParentType>.contained-reference-list` is the only
+ * canonical graph edge. A child remains an independent entry and therefore
+ * never receives `is-contained` or `contained-parent-reference` claims.
+ */
+export declare function linkFlatClaimResourceEntries(entries: readonly FlatClaimResourceEntry[], link: Readonly<{
+    parentEntryId: string;
+    childEntryIds: readonly string[];
+}>): readonly FlatClaimResourceEntry[];
+/** Adds language and XHTML narrative source without materializing native FHIR. */
+export declare function withFlatClaimNarrative(entry: FlatClaimResourceEntry, narrative: FlatClaimNarrative): FlatClaimResourceEntry;
+/** Reads legacy graphs without perpetuating child-owned containment state. */
+export declare function normalizeLegacyContainedClaims(entry: FlatClaimResourceEntry): FlatClaimResourceEntry;
+/**
+ * Builds one DocumentReference flat entry for a PDF, JPEG or PNG.
+ * Link one or many such entries from any clinical parent with
+ * `linkFlatClaimResourceEntries`; attachment bytes are not duplicated.
+ */
+export declare function buildDocumentReferenceFlatEntry(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    contentType: 'application/pdf' | 'image/jpeg' | 'image/png';
+    contentHash: string;
+    title?: string;
+    url?: string;
+    dataBase64?: string;
+}>): FlatClaimResourceEntry;