sos-sdk-core-ts 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## 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,

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/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.1",
+  "version": "0.5.2",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -73,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",