sos-sdk-core-ts 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.5.2 - 2026-10-04
+
+- Add runtime-neutral accepted-handover orchestration that prepares the
+  Encounter/EncounterHistory projection together with the retained, added and
+  removed professional Group audience and a family-safe journey event.
+- Preserve every inner resource identifier and project both provider-owned
+  Encounter snapshots with idempotent creates, so a subject index does not
+  require a prior copy of the source Encounter.
+- Consume the neutral emergency Group builders and remove the obsolete
+  product-prefixed helper names from SDK tests and examples.
+
+## 0.5.1 - 2026-10-04
+
+- Add the shared Bundle synchronization draft contract for clinical documents,
+  Consent, emergency contacts and Encounter transfers. Optimistic records stay
+  visibly pending after ambiguous or transient provider failures, definite
+  rejections restore the last confirmed Bundle, and only authoritative
+  provider readback marks a mutation as confirmed.
+
 - Add the claims-first Encounter transfer projection helper. It keeps a
   returning source `on-hold`, completes a definitive source departure, starts
   the destination `in-progress`, records both `EncounterHistory` milestones,

package/README.md

@@ -62,6 +62,13 @@ The shared scheduling and response-correlation boundary is documented in
 Source-to-destination care movement and subject-index projection are documented
 in [Encounter transfer projection](docs/ENCOUNTER_TRANSFER_PROJECTION.md).
 
+`BundleSyncDraft` is the shared serializable state for editors that must keep a
+local clinical document, Consent, emergency-contact or Encounter mutation
+visible while its provider write is pending. A successful HTTP response is not
+confirmation: the draft becomes `confirmed` only after authoritative provider
+readback. Ambiguous and transport failures remain `retryable`; definite remote
+rejections restore the last confirmed Bundle.
+
 The emergency-group contract stores subject references only on an enumerated
 FHIR Group. A group assistance request references that Group from one standard,
 compact-coded ServiceRequest; it never copies members or persists split coding

package/dist/bundle-sync-draft.d.ts

@@ -0,0 +1,61 @@
+import type { BundleEntry, BundleJsonApi } from 'gdc-common-utils-ts/models/bundle';
+export declare const BundleSyncKinds: Readonly<{
+    readonly ClinicalDocument: "clinical-document";
+    readonly EncounterTransfer: "encounter-transfer";
+    readonly Consent: "consent";
+    readonly EmergencyContact: "emergency-contact";
+}>;
+export type BundleSyncKind = typeof BundleSyncKinds[keyof typeof BundleSyncKinds];
+export declare const BundleSyncStates: Readonly<{
+    readonly Pending: "pending";
+    readonly Submitting: "submitting";
+    readonly Retryable: "retryable";
+    readonly Reconciling: "reconciling";
+    readonly Confirmed: "confirmed";
+    readonly Rejected: "rejected";
+}>;
+export type BundleSyncState = typeof BundleSyncStates[keyof typeof BundleSyncStates];
+export type BundleSyncPayload = BundleJsonApi<BundleEntry>;
+export type BundleSyncDraft = Readonly<{
+    id: string;
+    kind: BundleSyncKind;
+    subjectReference: string;
+    state: BundleSyncState;
+    changesBundle: BundleSyncPayload;
+    lastConfirmedBundle: BundleSyncPayload;
+    optimisticBundle?: BundleSyncPayload;
+    visibleBundle: BundleSyncPayload;
+    pendingIdentifiers: readonly string[];
+    diagnostics: readonly string[];
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type CreateBundleSyncDraftInput = Readonly<{
+    id: string;
+    kind: BundleSyncKind;
+    subjectReference: string;
+    changesBundle: BundleSyncPayload;
+    lastConfirmedBundle: BundleSyncPayload;
+    optimisticBundle: BundleSyncPayload;
+    createdAt: string;
+}>;
+/**
+ * Creates the portable, serializable state shown while the BFF owns delivery.
+ * The optimistic Bundle remains visibly marked by `state`; it is never proof
+ * of provider persistence.
+ */
+export declare function createBundleSyncDraft(input: CreateBundleSyncDraftInput): BundleSyncDraft;
+/** Marks a durable draft as actively submitted without changing its preview. */
+export declare function submitBundleSyncDraft(draft: BundleSyncDraft, updatedAt: string): BundleSyncDraft;
+/** Retains the exact optimistic draft after a transient transport failure. */
+export declare function markBundleSyncRetryable(draft: BundleSyncDraft, diagnostics: readonly string[], updatedAt: string): BundleSyncDraft;
+/**
+ * Interprets the correlated remote Bundle response.
+ *
+ * Missing or ambiguous results keep the optimistic Bundle as a retryable
+ * draft. A definite rejection removes it. Successful submission moves to
+ * reconciling and still requires an authoritative provider readback.
+ */
+export declare function reconcileBundleSyncSubmission(draft: BundleSyncDraft, responseBundle: BundleSyncPayload, updatedAt: string): BundleSyncDraft;
+/** Replaces the preview only after exact provider readback succeeds. */
+export declare function confirmBundleSyncDraft(draft: BundleSyncDraft, authoritativeBundle: BundleSyncPayload, updatedAt: string): BundleSyncDraft;

package/dist/bundle-sync-draft.js

@@ -0,0 +1,115 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+import { analyzeBundleChangesResponse } from './bundle-changes-response.js';
+export const BundleSyncKinds = Object.freeze({
+    ClinicalDocument: 'clinical-document',
+    EncounterTransfer: 'encounter-transfer',
+    Consent: 'consent',
+    EmergencyContact: 'emergency-contact',
+});
+export const BundleSyncStates = Object.freeze({
+    Pending: 'pending',
+    Submitting: 'submitting',
+    Retryable: 'retryable',
+    Reconciling: 'reconciling',
+    Confirmed: 'confirmed',
+    Rejected: 'rejected',
+});
+/**
+ * Creates the portable, serializable state shown while the BFF owns delivery.
+ * The optimistic Bundle remains visibly marked by `state`; it is never proof
+ * of provider persistence.
+ */
+export function createBundleSyncDraft(input) {
+    requireText(input.id, 'bundle_sync_id_required');
+    requireText(input.subjectReference, 'bundle_sync_subject_required');
+    requireText(input.createdAt, 'bundle_sync_created_at_required');
+    if (!Object.values(BundleSyncKinds).includes(input.kind))
+        throw new TypeError('bundle_sync_kind_invalid');
+    return Object.freeze({
+        ...input,
+        state: BundleSyncStates.Pending,
+        visibleBundle: input.optimisticBundle,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([]),
+        updatedAt: input.createdAt,
+    });
+}
+/** Marks a durable draft as actively submitted without changing its preview. */
+export function submitBundleSyncDraft(draft, updatedAt) {
+    if (![BundleSyncStates.Pending, BundleSyncStates.Retryable].includes(draft.state)) {
+        throw new TypeError('bundle_sync_not_submittable');
+    }
+    return Object.freeze({ ...draft, state: BundleSyncStates.Submitting, updatedAt });
+}
+/** Retains the exact optimistic draft after a transient transport failure. */
+export function markBundleSyncRetryable(draft, diagnostics, updatedAt) {
+    if ([BundleSyncStates.Confirmed, BundleSyncStates.Rejected].includes(draft.state)) {
+        throw new TypeError('bundle_sync_retry_not_allowed');
+    }
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Retryable,
+        diagnostics: Object.freeze([...diagnostics]),
+        updatedAt,
+    });
+}
+/**
+ * Interprets the correlated remote Bundle response.
+ *
+ * Missing or ambiguous results keep the optimistic Bundle as a retryable
+ * draft. A definite rejection removes it. Successful submission moves to
+ * reconciling and still requires an authoritative provider readback.
+ */
+export function reconcileBundleSyncSubmission(draft, responseBundle, updatedAt) {
+    if (![BundleSyncStates.Pending, BundleSyncStates.Submitting, BundleSyncStates.Retryable].includes(draft.state)) {
+        throw new TypeError('bundle_sync_response_not_expected');
+    }
+    const analysis = analyzeBundleChangesResponse(draft.changesBundle, responseBundle);
+    if (analysis.failedIdentifiers.length) {
+        return Object.freeze({
+            ...draft,
+            state: BundleSyncStates.Rejected,
+            optimisticBundle: undefined,
+            visibleBundle: draft.lastConfirmedBundle,
+            pendingIdentifiers: Object.freeze([]),
+            diagnostics: Object.freeze([...analysis.diagnostics, ...analysis.entries.flatMap(({ diagnostics }) => diagnostics)]),
+            updatedAt,
+        });
+    }
+    if (analysis.pendingIdentifiers.length) {
+        return Object.freeze({
+            ...draft,
+            state: BundleSyncStates.Retryable,
+            pendingIdentifiers: Object.freeze([...analysis.pendingIdentifiers]),
+            diagnostics: Object.freeze([...analysis.diagnostics]),
+            updatedAt,
+        });
+    }
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Reconciling,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([...analysis.diagnostics]),
+        updatedAt,
+    });
+}
+/** Replaces the preview only after exact provider readback succeeds. */
+export function confirmBundleSyncDraft(draft, authoritativeBundle, updatedAt) {
+    if (draft.state !== BundleSyncStates.Reconciling)
+        throw new TypeError('bundle_sync_readback_not_expected');
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Confirmed,
+        lastConfirmedBundle: authoritativeBundle,
+        optimisticBundle: undefined,
+        visibleBundle: authoritativeBundle,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([]),
+        updatedAt,
+    });
+}
+function requireText(value, issue) {
+    if (!value.trim())
+        throw new TypeError(issue);
+    return value;
+}

package/dist/communication-bundle.js

@@ -153,7 +153,16 @@ export class CommunicationMessageEditor extends CommunicationAttachedBundleSessi
             claims,
             fullUrl: `urn:uuid:${identifier}`,
             ...(request ? { request } : {}),
-        }).saveAndReleaseActiveEntry();
+        });
+        const activePosition = this.getActiveEntryPosition();
+        if (activePosition === null)
+            throw new TypeError('communication_bundle_active_entry_required');
+        const bundle = this.getAttachedBundle();
+        const activeResource = bundle.data[activePosition]?.resource;
+        if (!activeResource)
+            throw new TypeError('communication_bundle_active_resource_required');
+        activeResource.id = identifier;
+        this.setAttachedBundle(bundle).saveAndReleaseActiveEntry();
         return this;
     }
     /** Adds a PDF, image, audio or calendar file as an inner DocumentReference. */

package/dist/encounter-transfer-communication.d.ts

@@ -1,4 +1,8 @@
 import { type ClinicalCoding, type FhirResource } from 'fhir-data-utils-ts';
+import { type CareJourneyMovementKindValue, type EncounterCommunicationAudienceReconciliation } from 'sos-data-utils-ts/encounter-communication-audience';
+import type { ProfessionalServiceGroupAssignment } from 'sos-data-utils-ts/organization-service-catalog';
+export { CareJourneyMovementKind } from 'sos-data-utils-ts/encounter-communication-audience';
+export type { CareJourneyMovementKindValue, EncounterCommunicationAudienceReconciliation, } from 'sos-data-utils-ts/encounter-communication-audience';
 export type EncounterTransferSourceDisposition = 'returning' | 'not-returning';
 export type EncounterTransferProjectionInput = Readonly<{
     communicationIdentifier: string;
@@ -21,6 +25,18 @@ export type EncounterTransferProjectionInput = Readonly<{
     destinationHistoryIdentifier: string;
     encounterClass: ClinicalCoding;
 }>;
+export type EncounterTransferOrchestrationInput = EncounterTransferProjectionInput & Readonly<{
+    communicationThreadId: string;
+    movementKind: CareJourneyMovementKindValue;
+    sourceAssignments: readonly ProfessionalServiceGroupAssignment[];
+    destinationAssignments: readonly ProfessionalServiceGroupAssignment[];
+    currentProfessionalGroupReferences: readonly string[];
+    handoverAccepted: boolean;
+}>;
+export type EncounterTransferOrchestration = Readonly<{
+    projectionCommunication: Record<string, unknown>;
+    audienceReconciliation: EncounterCommunicationAudienceReconciliation;
+}>;
 /**
  * Builds the completed Communication used to project an already-committed
  * provider transfer to the subject index.
@@ -38,3 +54,15 @@ export type EncounterTransferProjectionInput = Readonly<{
  * into the FHIR sender, author or attester fields.
  */
 export declare function prepareEncounterTransferProjectionCommunication(input: EncounterTransferProjectionInput): Record<string, unknown>;
+/**
+ * Prepare one runtime-neutral transfer plan after the destination accepts
+ * handover.
+ *
+ * The product BFF authorizes the actor and resolves current service Group
+ * assignments before this call. Its persistence adapter then commits the
+ * Encounter/EncounterHistory transaction, the new future channel audience and
+ * the family-safe journey event under the same idempotency key. Historical
+ * Communication recipients remain immutable. This SDK neither stores state
+ * nor interprets Group membership as access authority.
+ */
+export declare function prepareEncounterTransferOrchestration(input: EncounterTransferOrchestrationInput): EncounterTransferOrchestration;

package/dist/encounter-transfer-communication.js

@@ -1,5 +1,7 @@
 import { EncounterClaim, EncounterHistoryClaim, EncounterStatusR5, buildEncounterHistoryR5FlatEntry, } from 'fhir-data-utils-ts';
+import { CareJourneyMovementKind, reconcileEncounterCommunicationAudience, } from 'sos-data-utils-ts/encounter-communication-audience';
 import { CommunicationBundleEditor } from './communication-bundle.js';
+export { CareJourneyMovementKind } from 'sos-data-utils-ts/encounter-communication-audience';
 /**
  * Builds the completed Communication used to project an already-committed
  * provider transfer to the subject index.
@@ -53,13 +55,60 @@ export function prepareEncounterTransferProjectionCommunication(input) {
         .setSent(input.occurredAt)
         .setAttachmentTitle('encounter-transfer-bundle.json')
         .setInnerBundleType('batch')
-        .addResource(sourceUpdated, { method: 'PUT', url: `Encounter/${sourceUpdated.id}` })
+        .addResource(sourceUpdated, { method: 'POST', url: 'Encounter' })
         .addResource(sourceHistory, { method: 'POST', url: 'EncounterHistory' })
-        .addResource(destinationUpdated, { method: 'PUT', url: `Encounter/${destinationUpdated.id}` })
+        .addResource(destinationUpdated, { method: 'POST', url: 'Encounter' })
         .addResource(destinationHistory, { method: 'POST', url: 'EncounterHistory' })
         .doneCommunication();
     return editor.build();
 }
+/**
+ * Prepare one runtime-neutral transfer plan after the destination accepts
+ * handover.
+ *
+ * The product BFF authorizes the actor and resolves current service Group
+ * assignments before this call. Its persistence adapter then commits the
+ * Encounter/EncounterHistory transaction, the new future channel audience and
+ * the family-safe journey event under the same idempotency key. Historical
+ * Communication recipients remain immutable. This SDK neither stores state
+ * nor interprets Group membership as access authority.
+ */
+export function prepareEncounterTransferOrchestration(input) {
+    assertMovementMatchesDisposition(input.movementKind, input.sourceDisposition);
+    const source = normalizeEncounter(input.sourceEncounter, input.subjectReference);
+    const destination = normalizeEncounter(input.destinationEncounter, input.subjectReference);
+    const sourceStatus = input.sourceDisposition === 'returning'
+        ? EncounterStatusR5.OnHold
+        : EncounterStatusR5.Completed;
+    const projectionCommunication = prepareEncounterTransferProjectionCommunication(input);
+    const audienceReconciliation = reconcileEncounterCommunicationAudience({
+        idempotencyKey: input.communicationIdentifier,
+        communicationThreadId: input.communicationThreadId,
+        subjectReference: input.subjectReference,
+        movementKind: input.movementKind,
+        sourceEncounterReference: `Encounter/${source.id}`,
+        sourceEncounterStatus: sourceStatus,
+        sourceHealthcareServiceReference: text(claimsOf(source)[EncounterClaim.ServiceType]),
+        sourceAssignments: input.sourceAssignments,
+        destinationEncounterReference: `Encounter/${destination.id}`,
+        destinationEncounterStatus: EncounterStatusR5.InProgress,
+        destinationHealthcareServiceReference: text(claimsOf(destination)[EncounterClaim.ServiceType]),
+        destinationAssignments: input.destinationAssignments,
+        currentProfessionalGroupReferences: input.currentProfessionalGroupReferences,
+        occurredAt: input.occurredAt,
+        handoverAccepted: input.handoverAccepted,
+    });
+    return Object.freeze({ projectionCommunication, audienceReconciliation });
+}
+function assertMovementMatchesDisposition(movementKind, sourceDisposition) {
+    const matches = movementKind === CareJourneyMovementKind.TemporaryTransfer
+        ? sourceDisposition === 'returning'
+        : (movementKind === CareJourneyMovementKind.PermanentTransfer
+            || movementKind === CareJourneyMovementKind.ReturnTransfer)
+            && sourceDisposition === 'not-returning';
+    if (!matches)
+        throw new TypeError('encounter_transfer_movement_disposition_mismatch');
+}
 function normalizeEncounter(resource, subjectReference) {
     if (resource.resourceType !== 'Encounter')
         throw new TypeError('fhir_encounter_required');

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './communication-bundle.js';
 export * from './fhir-scheduling.js';
 export * from './bundle-changes-response.js';
 export * from './encounter-transfer-communication.js';
+export * from './bundle-sync-draft.js';

package/dist/index.js

@@ -8,3 +8,4 @@ export * from './communication-bundle.js';
 export * from './fhir-scheduling.js';
 export * from './bundle-changes-response.js';
 export * from './encounter-transfer-communication.js';
+export * from './bundle-sync-draft.js';

package/docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md

@@ -14,14 +14,18 @@ human policy stays in Vet and UHC.
 3. Admission, diagnostics, intensive care, ward and discharge are represented
    by Encounter/location continuity. Controllers see only what current Consent
    and actor/subject authorization permit.
-4. An authorized practitioner may start voice/video contact or send an
+4. Accepted service handover reconciles the future professional audience from
+   exact HealthcareService Group assignments. Temporary movement retains the
+   source Groups; definitive movement removes them. Historical Communication
+   recipients are immutable.
+5. An authorized practitioner may start voice/video contact or send an
    encrypted message to the controller or permitted related recipients before
    publishing stressful results.
-5. Voice/video signaling carries no clinical Bundle. A preliminary clinical
+6. Voice/video signaling carries no clinical Bundle. A preliminary clinical
    Bundle may be delivered by encrypted message only with `updateIndex=false`.
    A call or preliminary message must not publish, attest or update the subject
    index. Final clinical publication is a separate workflow.
-6. A missed call may create an encrypted text/audio message in the same thread;
+7. A missed call may create an encrypted text/audio message in the same thread;
    its recipients and thread authorization are revalidated by the service.
 
 The orchestrator returns a plan. The persistence owner must enforce the

package/docs/ENCOUNTER_TRANSFER_PROJECTION.md

@@ -18,6 +18,43 @@ After the provider has committed those four records, it can call
 completed `Communication` whose inner batch Bundle projects the same four
 changes to the subject-index provider. The Communication is continuity and
 discovery evidence; it is not a substitute for the provider transaction.
+Both Encounter snapshots use idempotent `POST Encounter` commands because the
+provider may already hold an Encounter that the subject index has never seen.
+Their stable resource identifiers let the receiver return create-or-existing
+readback without requiring a prior index record. Each milestone uses
+`POST EncounterHistory` and retains its own stable identifier.
+
+For a channel that follows the patient's journey, call
+`prepareEncounterTransferOrchestration(...)` after the destination accepts the
+handover. It returns the same projection Communication together with an
+idempotent professional-Group audience reconciliation and a family-safe journey
+event:
+
+```ts
+const transferPlan = prepareEncounterTransferOrchestration({
+  ...encounterProjectionInput,
+  communicationThreadId: emergencyThreadId,
+  movementKind: patientWillReturn
+    ? CareJourneyMovementKind.TemporaryTransfer
+    : CareJourneyMovementKind.PermanentTransfer,
+  sourceAssignments: authorizedSourceServiceGroups,
+  destinationAssignments: authorizedDestinationServiceGroups,
+  currentProfessionalGroupReferences,
+  handoverAccepted: true,
+})
+```
+
+The runtime persists the provider Encounter transaction, future channel
+audience and journey event under the same idempotency key. A permanent transfer
+removes the departed service Groups. A temporary transfer retains them while
+adding the temporary destination Groups. Returning is another accepted
+movement with the temporary Encounter as source and the resumed Encounter as
+destination.
+
+Only future messages use the reconciled audience. Previously sent
+Communications keep their original recipient snapshots. Family recipients
+receive the separately authorized journey projection, never professional Group
+membership or internal clinical messages.
 
 The department Organization is `Communication.sender`. Each Encounter keeps an
 explicit `HealthcareService`. The authenticated professional/device remains

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -47,6 +47,10 @@
     "./encounter-transfer-communication": {
       "types": "./dist/encounter-transfer-communication.d.ts",
       "default": "./dist/encounter-transfer-communication.js"
+    },
+    "./bundle-sync-draft": {
+      "types": "./dist/bundle-sync-draft.d.ts",
+      "default": "./dist/bundle-sync-draft.js"
     }
   },
   "files": [
@@ -69,7 +73,7 @@
     "@noble/post-quantum": "0.7.1",
     "fhir-data-utils-ts": "0.6.1",
     "gdc-common-utils-ts": "2.9.21",
-    "sos-data-utils-ts": "0.6.0"
+    "sos-data-utils-ts": "0.6.5"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",