sos-sdk-core-ts 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+- Require the initial emergency triage Task owner to be a professional Group,
+  while keeping the accepting PractitionerRole as Task owner and actual
+  callback/message sender after acknowledgement.
+- Clarify that Group reply routing never replaces the legal Organization
+  document author, professional attester or authenticated transport actor.
+
+## 0.3.1 - 2026-09-27
+
+- Pin the latest already-published `sos-data-utils-ts@0.4.2` baseline while
+  grouped unreleased Task lifecycle changes continue through immutable local
+  tarballs.
+- Add high-level emergency triage Task readers and deterministic
+  acknowledge/start/escalate/reject/complete transitions without rewriting the
+  originating ServiceRequest.
+- Preserve the protected communication-thread correlation on the Task and
+  authorize responder callbacks only for the accepted or in-progress Task
+  owner; endpoint resolution and signaling remain product-server concerns.
+
 ## 0.3.0 - 2026-09-26
 
 - Pin `sos-data-utils-ts@0.4.1`, which owns the Organization fallback target

package/README.md

@@ -63,10 +63,16 @@ a canonical SOSChain Place or vehicle without merging either identity.
 `sos-sdk-core-ts/care-emergency-alert-orchestration` supplies the shared,
 runtime-neutral plans for Appointment-to-Encounter continuity, protected
 pre-publication calls/messages, resilient emergency ServiceRequest plus triage
-Task creation, and governed donation/public-risk campaigns. Transport,
+Task creation/transition/responder callback authorization, and governed
+donation/public-risk campaigns. Transport,
 persistence, authorization evidence acquisition and product policy remain in
 the channel service, Node adapter and Vet/UHC/SOSChain layers.
 
+Emergency triage starts with a professional Group owner and changes to the
+accepting PractitionerRole. The Group remains a reply queue, never the
+clinical-document author or human Communication sender; those identities stay
+separate from the professional attester and transport audit evidence.
+
 See [docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md](docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md)
 for lifecycle, authorization and persistence invariants.
 

package/dist/care-emergency-alert-orchestration.d.ts

@@ -54,6 +54,53 @@ export declare function orchestrateEmergencyRequest(input: Readonly<{
     serviceRequestEntry: FlatClaimResourceEntry;
     triageTaskEntry: FlatClaimResourceEntry;
 }>;
+export type EmergencyTriageAction = 'acknowledge' | 'start' | 'escalate' | 'reject' | 'complete';
+export type EmergencyTriageTask = Readonly<{
+    taskReference: string;
+    status: string;
+    focusReference: string;
+    subjectReference: string;
+    requesterReference: string;
+    ownerReference: string;
+    authoredAt: string;
+    communicationThreadId?: string;
+    lastModified?: string;
+}>;
+/**
+ * Reads only the standard, claims-first coordinates required by a responder
+ * console. It does not resolve contact endpoints or grant callback authority.
+ */
+export declare function readEmergencyTriageTask(taskEntry: FlatClaimResourceEntry): EmergencyTriageTask;
+/**
+ * Applies one deterministic responder transition to the Task only. The
+ * ServiceRequest remains immutable; callers must authorize the responder and
+ * resolve any escalation owner before invoking this function.
+ */
+export declare function transitionEmergencyTriageTask(input: Readonly<{
+    taskEntry: FlatClaimResourceEntry;
+    action: EmergencyTriageAction;
+    responderReference: string;
+    escalationOwnerReference?: string;
+    occurredAt: string;
+}>): FlatClaimResourceEntry;
+export type EmergencyResponderCallback = Readonly<{
+    taskReference: string;
+    serviceRequestReference: string;
+    subjectReference: string;
+    requesterReference: string;
+    responderReference: string;
+    communicationThreadId: string;
+    media: 'audio' | 'video';
+}>;
+/**
+ * Authorizes callback correlation for the current Task owner. Protected
+ * endpoint resolution and WebRTC signaling remain in the product server.
+ */
+export declare function prepareEmergencyResponderCallback(input: Readonly<{
+    taskEntry: FlatClaimResourceEntry;
+    responderReference: string;
+    media: 'audio' | 'video';
+}>): EmergencyResponderCallback;
 export type GovernedAlertCampaignPlan = Readonly<{
     campaign: GovernedAlertCampaign;
     cohortSnapshot: GovernedAlertCohortSnapshot;

package/dist/care-emergency-alert-orchestration.js

@@ -1,4 +1,5 @@
 import { freezeGovernedAlertCohort, normalizeCareJourneyTransition, normalizeEmergencyIntake, normalizeGovernedAlertCampaign, recordGovernedAlertDelivery, } from 'sos-data-utils-ts/care-emergency-alert-records';
+import { TaskClaim, TaskStatus } from 'sos-data-utils-ts/task-artifact-schema';
 import { buildCohortCommunicationRequestFlatEntry, buildEncounterCareJourneyFlatGraph, buildServiceRequestFlatEntry, buildServiceRequestTriageTaskFlatEntry, } from 'fhir-data-utils-ts/care-emergency-alert';
 /**
  * Plans one idempotent Appointment-to-Encounter transition. Persistence must
@@ -57,6 +58,7 @@ export function authorizeEncounterCommunication(input) {
 /** Creates independent standard ServiceRequest and durable triage Task entries. */
 export function orchestrateEmergencyRequest(input) {
     const intake = normalizeEmergencyIntake(input.intake);
+    const triageGroupReference = reference(intake.triageOwnerReference, 'Group', 'emergency_triage_group_owner_required');
     const serviceRequestEntry = buildServiceRequestFlatEntry({
         entryId: intake.serviceRequestEntryId,
         identifier: input.serviceRequestIdentifier,
@@ -69,17 +71,135 @@ export function orchestrateEmergencyRequest(input) {
         performerReferences: [intake.targetServiceReference],
         authoredAt: intake.receivedAt,
     });
-    const triageTaskEntry = buildServiceRequestTriageTaskFlatEntry({
+    const baseTriageTaskEntry = buildServiceRequestTriageTaskFlatEntry({
         entryId: intake.triageTaskEntryId,
         identifier: input.triageTaskIdentifier,
         serviceRequestReference: serviceRequestEntry.reference,
         subjectReference: intake.subjectReference,
         requesterReference: intake.requesterReference,
-        ownerReference: intake.triageOwnerReference,
+        ownerReference: triageGroupReference,
         authoredAt: intake.receivedAt,
     });
+    const triageTaskEntry = Object.freeze({
+        ...baseTriageTaskEntry,
+        claims: Object.freeze({
+            ...baseTriageTaskEntry.claims,
+            [TaskClaim.GroupIdentifier]: intake.communicationThreadId,
+        }),
+    });
     return Object.freeze({ intake, serviceRequestEntry, triageTaskEntry });
 }
+// Compatibility overlay for the published data package used by clean installs.
+// The next grouped release exposes the same standard values directly there.
+const EmergencyTaskStatus = Object.freeze({
+    ...TaskStatus,
+    Received: 'received',
+    Accepted: 'accepted',
+    Rejected: 'rejected',
+    Ready: 'ready',
+    OnHold: 'on-hold',
+    EnteredInError: 'entered-in-error',
+});
+/**
+ * Reads only the standard, claims-first coordinates required by a responder
+ * console. It does not resolve contact endpoints or grant callback authority.
+ */
+export function readEmergencyTriageTask(taskEntry) {
+    if (taskEntry.resourceType !== 'Task' || taskEntry.reference !== `Task/${taskEntry.entryId}`) {
+        throw new TypeError('emergency_triage_task_invalid');
+    }
+    const claims = taskEntry.claims;
+    const status = scalarClaim(claims[TaskClaim.Status], 'emergency_triage_status_required');
+    if (!Object.values(EmergencyTaskStatus).includes(status)) {
+        throw new TypeError('emergency_triage_status_invalid');
+    }
+    return Object.freeze({
+        taskReference: taskEntry.reference,
+        status,
+        focusReference: reference(scalarClaim(claims[TaskClaim.Focus], 'emergency_triage_focus_required'), 'ServiceRequest', 'emergency_triage_focus_invalid'),
+        subjectReference: reference(scalarClaim(claims[TaskClaim.For], 'emergency_triage_subject_required'), undefined, 'emergency_triage_subject_invalid'),
+        requesterReference: reference(scalarClaim(claims[TaskClaim.Requester], 'emergency_triage_requester_required'), undefined, 'emergency_triage_requester_invalid'),
+        ownerReference: reference(scalarClaim(claims[TaskClaim.Owner], 'emergency_triage_owner_required'), undefined, 'emergency_triage_owner_invalid'),
+        authoredAt: dateTime(scalarClaim(claims[TaskClaim.AuthoredOn], 'emergency_triage_authored_on_required'), 'emergency_triage_authored_on_invalid'),
+        ...(claims[TaskClaim.GroupIdentifier]
+            ? { communicationThreadId: scalarClaim(claims[TaskClaim.GroupIdentifier], 'emergency_triage_thread_invalid') }
+            : {}),
+        ...(claims[TaskClaim.LastModified]
+            ? { lastModified: dateTime(scalarClaim(claims[TaskClaim.LastModified], 'emergency_triage_last_modified_invalid'), 'emergency_triage_last_modified_invalid') }
+            : {}),
+    });
+}
+/**
+ * Applies one deterministic responder transition to the Task only. The
+ * ServiceRequest remains immutable; callers must authorize the responder and
+ * resolve any escalation owner before invoking this function.
+ */
+export function transitionEmergencyTriageTask(input) {
+    const current = readEmergencyTriageTask(input.taskEntry);
+    const responderReference = reference(input.responderReference, 'PractitionerRole', 'emergency_triage_responder_invalid');
+    const transition = emergencyTriageTransition(current.status, input.action);
+    const ownerReference = input.action === 'escalate'
+        ? reference(input.escalationOwnerReference, undefined, 'emergency_triage_escalation_owner_required')
+        : input.action === 'acknowledge'
+            ? responderReference
+            : current.ownerReference;
+    const claims = {
+        ...input.taskEntry.claims,
+        [TaskClaim.Status]: transition,
+        [TaskClaim.Owner]: ownerReference,
+        [TaskClaim.LastModified]: dateTime(input.occurredAt, 'emergency_triage_occurred_at_invalid'),
+        ...(input.action === 'escalate' ? { [TaskClaim.EscalationRecipient]: ownerReference } : {}),
+    };
+    return Object.freeze({ ...input.taskEntry, claims: Object.freeze(claims) });
+}
+/**
+ * Authorizes callback correlation for the current Task owner. Protected
+ * endpoint resolution and WebRTC signaling remain in the product server.
+ */
+export function prepareEmergencyResponderCallback(input) {
+    const task = readEmergencyTriageTask(input.taskEntry);
+    const responderReference = reference(input.responderReference, 'PractitionerRole', 'emergency_callback_responder_invalid');
+    if (task.ownerReference !== responderReference)
+        throw new TypeError('emergency_callback_task_owner_required');
+    if (task.status !== EmergencyTaskStatus.Accepted && task.status !== EmergencyTaskStatus.InProgress) {
+        throw new TypeError('emergency_callback_active_task_required');
+    }
+    if (!task.communicationThreadId)
+        throw new TypeError('emergency_callback_thread_required');
+    if (input.media !== 'audio' && input.media !== 'video')
+        throw new TypeError('emergency_callback_media_invalid');
+    return Object.freeze({
+        taskReference: task.taskReference,
+        serviceRequestReference: task.focusReference,
+        subjectReference: task.subjectReference,
+        requesterReference: task.requesterReference,
+        responderReference,
+        communicationThreadId: task.communicationThreadId,
+        media: input.media,
+    });
+}
+function emergencyTriageTransition(currentStatus, action) {
+    const transitions = {
+        acknowledge: { [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Accepted, [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Accepted },
+        start: { [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.InProgress, [EmergencyTaskStatus.Ready]: EmergencyTaskStatus.InProgress },
+        escalate: {
+            [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Requested,
+            [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Requested,
+            [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.Requested,
+            [EmergencyTaskStatus.InProgress]: EmergencyTaskStatus.Requested,
+        },
+        reject: {
+            [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Rejected,
+            [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Rejected,
+            [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.Rejected,
+        },
+        complete: { [EmergencyTaskStatus.InProgress]: EmergencyTaskStatus.Completed },
+    };
+    const nextStatus = transitions[action]?.[currentStatus];
+    if (!nextStatus)
+        throw new TypeError('emergency_triage_transition_invalid');
+    return nextStatus;
+}
 /** Builds one campaign request bound to the frozen evaluated Group snapshot. */
 export function prepareGovernedAlertCampaign(input) {
     const campaign = normalizeGovernedAlertCampaign(input.campaign);
@@ -122,6 +242,18 @@ export function prepareGovernedAlertDelivery(input) {
         outcome: input.outcome,
     });
 }
+function scalarClaim(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}
+function dateTime(value, error) {
+    const normalized = scalarClaim(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}T/u.test(normalized) || Number.isNaN(Date.parse(normalized))) {
+        throw new TypeError(error);
+    }
+    return normalized;
+}
 function uniqueReferences(values, error) {
     const references = [...new Set(values.map(value => reference(value, undefined, error)))];
     if (!references.length)

package/docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md

@@ -37,7 +37,8 @@ independent resources:
 - a compact-coded ServiceRequest containing the care request, requester,
   subject and performer target;
 - a Task containing durable intake/triage ownership and linking back through
-  `Task.focus`.
+  `Task.focus`. Its initial owner is the professional Group assigned to the
+  target department/service.
 
 The emergency console can claim and update the Task, then open an authorized
 voice/video callback or encrypted thread. Raw phone/email destinations,
@@ -45,6 +46,38 @@ WebRTC SDP/ICE/TURN state and encryption keys never enter either FHIR resource.
 The request grants no read access by itself; subject access still requires the
 current emergency or ordinary authorization contract.
 
+The high-level API keeps reads and writes explicit:
+
+```ts
+const triageTask = readEmergencyTriageTask(claimsFirstTaskEntry)
+const acceptedTaskEntry = transitionEmergencyTriageTask({
+  taskEntry: claimsFirstTaskEntry,
+  action: 'acknowledge',
+  responderReference: authenticatedPractitionerRoleReference,
+  occurredAt: serverTime,
+})
+const callback = prepareEmergencyResponderCallback({
+  taskEntry: acceptedTaskEntry,
+  responderReference: authenticatedPractitionerRoleReference,
+  media: 'audio',
+})
+```
+
+`transitionEmergencyTriageTask(...)` changes only the Task. It never rewrites
+the ServiceRequest. Acknowledgement assigns the authenticated responder;
+escalation requires a server-resolved owner and returns the Task to
+`requested`. Callback authorization requires the accepted/in-progress Task
+owner and returns only stable references plus the protected thread
+correlation. The product server must still resolve the current encrypted
+recipient endpoints and signaling transport.
+
+The initial Group is the service queue, not a document author or a human
+sender. Once accepted, `Task.owner` is the acting `PractitionerRole`; that role
+is also the Communication/call sender. Controller/member replies are addressed
+to the stable department Group route retained by the protected thread. The
+legal Organization remains the author of any later clinical document, and its
+professional attester and authenticated transport actor remain separate.
+
 ## 3. Governed alerts
 
 The common flow supports both `blood-donation` and `public-risk` campaigns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -56,7 +56,7 @@
     "@noble/hashes": "2.4.0",
     "@noble/post-quantum": "0.7.1",
     "fhir-data-utils-ts": "0.3.7",
-    "sos-data-utils-ts": "0.4.1"
+    "sos-data-utils-ts": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",