sos-sdk-core-ts 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## 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
+  and governed public-risk campaign criteria used by this release.
+- Add idempotent fulfilled-Appointment to Encounter orchestration with
+  Appointment, subject, service provider and current Location continuity.
+- Add fail-closed authorization for encounter-related voice, video and secure
+  messages. Calls never carry clinical Bundles, and preliminary Bundles may be
+  delivered only without updating the subject index.
+- Create independent compact-coded emergency ServiceRequest and triage Task
+  entries targeting a HealthcareService or its owning Organization.
+- Add frozen-cohort CommunicationRequest orchestration and per-recipient
+  delivery checks for blood-donation and governed FHIR SearchParameter
+  public-risk campaigns.
+- Replace copied emergency Group members and split coding claims with the
+  canonical Group-reference and compact-code contract.
+- Document the immutable main-tarball local Vet proof required before npm
+  publication and staging.
+
 ## 0.2.2 - 2026-09-25
 
 - Add runtime-neutral ML-KEM-768 multi-recipient encryption for written and

package/README.md

@@ -1,12 +1,15 @@
 # Shared SOS SDK Core
 ## Blocking local-first SDK release
 
-The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its
-indivisible order is **local packages -> full local test matrix -> merge every
-validated branch to `main` -> publish bottom-up -> install exact registry
-versions and commit lockfiles on `main` -> staging**. Never publish to discover
-deterministic failures and never commit a local package reference. Staging
-begins only after exact registry packages are installed and verified.
+The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md).
+Merge and push validated shared dependency sources to `main`, create immutable
+unpublished tarballs from those main commits with `npm pack`, and install them
+temporarily with `--no-save`. Prove the real local Vet channel (portal, phone
+service, chatbot or other supported channel) -> BFF or channel service ->
+high-level SDK -> GW VET journey without skips. Then merge the consumer source
+to `main`, publish the exact commits bottom-up, pin exact registry versions and
+lockfiles, repeat affected local gates, and only then promote to staging.
+Never commit a tarball or `file:`, Git or workspace dependency.
 
 
 Runtime-neutral shared SDK for SOSChain, VetChain and UHC. Deterministic
@@ -35,13 +38,11 @@ jobs; those adapters do not belong here.
 Git, workspace, vendored and `file:` dependencies are forbidden in committed
 or deployed dependency state.
 
-The emergency-group contract treats `emergencyGroupId`, `subjectId` and
-`callerId` as opaque business identifiers. A group assistance request is one
-flat `ServiceRequest.*` claims under `resource.meta.claims`. A FHIR R5, R6 or
-other resource is projected only at an integration boundary.
-
-Groups are named collections. A scanned card is attached to one selected group
-before that group's identifiers are projected into a single service request.
+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
+claims. Flat claims remain the canonical storage representation and native
+FHIR is projected only at an explicit boundary.
 
 `authorizeEmergencyAction` separately checks trusted evidence for every
 member and for `sos:call` or `sos:request`. Identity verification alone never
@@ -57,6 +58,24 @@ to the same types and implementation; they are not a second contract.
 `buildSoschainPlaceCardAssociationClaims` records a UHC/VetChain card link to
 a canonical SOSChain Place or vehicle without merging either identity.
 
+## Care, emergency and alert orchestration
+
+`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/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.
+
 ## Multi-recipient secure messages
 
 `sos-sdk-core-ts/secure-message-crypto` protects written and binary-audio

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

@@ -0,0 +1,131 @@
+import { type CareJourneyTransition, type EmergencyIntake, type GovernedAlertCampaign, type GovernedAlertCohortSnapshot, type GovernedAlertDeliveryAudit } from 'sos-data-utils-ts/care-emergency-alert-records';
+import { type ClinicalCoding } from 'fhir-data-utils-ts/care-emergency-alert';
+import type { FlatClaimResourceEntry } from 'fhir-data-utils-ts/flat-claim-resource-graph';
+export type FulfilledAppointmentEncounterPlan = Readonly<{
+    created: false;
+    encounterReference: string;
+}> | Readonly<{
+    created: true;
+    encounterReference: string;
+    encounterEntry: FlatClaimResourceEntry;
+}>;
+/**
+ * Plans one idempotent Appointment-to-Encounter transition. Persistence must
+ * enforce `idempotencyKey`; an existing reference suppresses duplicate writes.
+ */
+export declare function orchestrateFulfilledAppointment(input: Readonly<{
+    transition: CareJourneyTransition;
+    encounterIdentifier: string;
+    existingEncounterReference?: string;
+}>): FulfilledAppointmentEncounterPlan;
+export type EncounterCommunicationAuthorization = Readonly<{
+    encounterReference: string;
+    actorReference: string;
+    recipientReferences: readonly string[];
+    channel: 'voice' | 'video' | 'encrypted-message';
+    includesClinicalBundle: boolean;
+    clinicalStatus?: 'preliminary' | 'final';
+    updateIndex: boolean;
+}>;
+/**
+ * Authorizes only the channel boundary. It never attests clinical data.
+ * Preliminary encrypted Bundles may be delivered directly but cannot update
+ * the subject index; voice/video signaling cannot carry a clinical Bundle.
+ */
+export declare function authorizeEncounterCommunication(input: Readonly<{
+    encounterReference: string;
+    actorReference: string;
+    recipientReferences: readonly string[];
+    actorCanCommunicate: boolean;
+    encounterActive: boolean;
+    channel: EncounterCommunicationAuthorization['channel'];
+    includesClinicalBundle: boolean;
+    clinicalStatus?: 'preliminary' | 'final';
+    updateIndex: boolean;
+}>): EncounterCommunicationAuthorization;
+/** Creates independent standard ServiceRequest and durable triage Task entries. */
+export declare function orchestrateEmergencyRequest(input: Readonly<{
+    intake: EmergencyIntake;
+    serviceRequestIdentifier: string;
+    triageTaskIdentifier: string;
+    assistanceCode: ClinicalCoding;
+}>): Readonly<{
+    intake: EmergencyIntake;
+    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;
+    communicationRequestEntry: FlatClaimResourceEntry;
+}>;
+/** Builds one campaign request bound to the frozen evaluated Group snapshot. */
+export declare function prepareGovernedAlertCampaign(input: Readonly<{
+    campaign: GovernedAlertCampaign;
+    snapshotGroupReference: string;
+    evaluatedAt: string;
+    evaluationFingerprint: string;
+    eligibleSubjectReferences: readonly string[];
+    communicationRequestEntryId: string;
+    communicationRequestIdentifier: string;
+    category: ClinicalCoding;
+}>): GovernedAlertCampaignPlan;
+/** Rechecks frozen membership before recording the data-layer delivery audit. */
+export declare function prepareGovernedAlertDelivery(input: Readonly<{
+    campaignPlan: GovernedAlertCampaignPlan;
+    recipientReference: string;
+    communicationReference: string;
+    evaluatedAt: string;
+    eligibilityCurrent: boolean;
+    exclusionCurrent: boolean;
+    consentReference?: string;
+    channelAuthorizationReference?: string;
+    outcome: 'sent' | 'suppressed';
+}>): GovernedAlertDeliveryAudit;

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

@@ -0,0 +1,271 @@
+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
+ * enforce `idempotencyKey`; an existing reference suppresses duplicate writes.
+ */
+export function orchestrateFulfilledAppointment(input) {
+    const transition = normalizeCareJourneyTransition(input.transition);
+    if (input.existingEncounterReference) {
+        return Object.freeze({
+            created: false,
+            encounterReference: reference(input.existingEncounterReference, 'Encounter', 'existing_encounter_reference_invalid'),
+        });
+    }
+    const encounterEntry = buildEncounterCareJourneyFlatGraph({
+        parent: {
+            entryId: transition.encounterEntryId,
+            identifier: input.encounterIdentifier,
+            status: 'in-progress',
+            subjectReference: transition.subjectReference,
+            appointmentReference: transition.appointmentReference,
+            serviceProviderReference: transition.serviceProviderReference,
+            periodStart: transition.occurredAt,
+            locationReference: transition.locationReference,
+        },
+    })[0];
+    return Object.freeze({ created: true, encounterReference: encounterEntry.reference, encounterEntry });
+}
+/**
+ * Authorizes only the channel boundary. It never attests clinical data.
+ * Preliminary encrypted Bundles may be delivered directly but cannot update
+ * the subject index; voice/video signaling cannot carry a clinical Bundle.
+ */
+export function authorizeEncounterCommunication(input) {
+    if (!input.actorCanCommunicate)
+        throw new Error('encounter_communication_actor_forbidden');
+    if (!input.encounterActive)
+        throw new Error('encounter_communication_inactive_encounter');
+    if ((input.channel === 'voice' || input.channel === 'video') && input.includesClinicalBundle) {
+        throw new Error('encounter_call_clinical_bundle_forbidden');
+    }
+    if (input.includesClinicalBundle && !input.clinicalStatus)
+        throw new Error('encounter_communication_clinical_status_required');
+    if (input.clinicalStatus === 'preliminary' && input.updateIndex)
+        throw new Error('preliminary_clinical_index_update_forbidden');
+    const recipientReferences = uniqueReferences(input.recipientReferences, 'encounter_communication_recipient_required');
+    return Object.freeze({
+        encounterReference: reference(input.encounterReference, 'Encounter', 'encounter_communication_encounter_reference_invalid'),
+        actorReference: reference(input.actorReference, undefined, 'encounter_communication_actor_reference_invalid'),
+        recipientReferences,
+        channel: input.channel,
+        includesClinicalBundle: input.includesClinicalBundle,
+        ...(input.clinicalStatus ? { clinicalStatus: input.clinicalStatus } : {}),
+        updateIndex: input.updateIndex,
+    });
+}
+/** 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,
+        status: 'active',
+        intent: 'order',
+        priority: 'stat',
+        code: input.assistanceCode,
+        subjectReference: intake.subjectReference,
+        requesterReference: intake.requesterReference,
+        performerReferences: [intake.targetServiceReference],
+        authoredAt: intake.receivedAt,
+    });
+    const baseTriageTaskEntry = buildServiceRequestTriageTaskFlatEntry({
+        entryId: intake.triageTaskEntryId,
+        identifier: input.triageTaskIdentifier,
+        serviceRequestReference: serviceRequestEntry.reference,
+        subjectReference: intake.subjectReference,
+        requesterReference: intake.requesterReference,
+        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);
+    const cohortSnapshot = freezeGovernedAlertCohort({
+        campaign,
+        snapshotGroupReference: input.snapshotGroupReference,
+        evaluatedAt: input.evaluatedAt,
+        evaluationFingerprint: input.evaluationFingerprint,
+        eligibleSubjectReferences: input.eligibleSubjectReferences,
+    });
+    const communicationRequestEntry = buildCohortCommunicationRequestFlatEntry({
+        entryId: input.communicationRequestEntryId,
+        identifier: input.communicationRequestIdentifier,
+        status: 'active',
+        priority: 'routine',
+        category: input.category,
+        subjectReference: cohortSnapshot.snapshotGroupReference,
+        requesterReference: campaign.requesterReference,
+        authoredAt: cohortSnapshot.evaluatedAt,
+        reasonReferences: [campaign.groupDefinitionReference],
+    });
+    return Object.freeze({ campaign, cohortSnapshot, communicationRequestEntry });
+}
+/** Rechecks frozen membership before recording the data-layer delivery audit. */
+export function prepareGovernedAlertDelivery(input) {
+    const recipientReference = reference(input.recipientReference, undefined, 'alert_delivery_recipient_reference_invalid');
+    if (!input.campaignPlan.cohortSnapshot.eligibleSubjectReferences.includes(recipientReference)) {
+        throw new Error('alert_delivery_recipient_not_in_snapshot');
+    }
+    return recordGovernedAlertDelivery({
+        campaignId: input.campaignPlan.campaign.campaignId,
+        snapshotGroupReference: input.campaignPlan.cohortSnapshot.snapshotGroupReference,
+        recipientReference,
+        communicationReference: input.communicationReference,
+        evaluatedAt: input.evaluatedAt,
+        eligibilityCurrent: input.eligibilityCurrent,
+        exclusionCurrent: input.exclusionCurrent,
+        consentReference: input.consentReference,
+        channelAuthorizationReference: input.channelAuthorizationReference,
+        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)
+        throw new TypeError(error);
+    return Object.freeze(references);
+}
+function reference(value, expectedType, error) {
+    if (typeof value !== 'string')
+        throw new TypeError(error);
+    const normalized = value.trim();
+    const match = /^([A-Z][A-Za-z0-9]+)\/([A-Za-z0-9.-]{1,128})$/.exec(normalized);
+    if (!match || (expectedType && match[1] !== expectedType))
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { EmergencyCapabilities, EvidenceDomains, EvidenceRelationships, Soschain
 export type { EvidenceRelationship, SoschainEvidenceRelationship, } from 'sos-data-utils-ts/emergency-evidence';
 export * from './emergency-group.js';
 export * from './emergency-authorization.js';
+export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
 export * from './secure-message-crypto.js';

package/dist/index.js

@@ -2,5 +2,6 @@
 export { EmergencyCapabilities, EvidenceDomains, EvidenceRelationships, SoschainEmergencyCapabilities, SoschainEvidenceDomains, SoschainEvidenceRelationships, } from 'sos-data-utils-ts/emergency-evidence';
 export * from './emergency-group.js';
 export * from './emergency-authorization.js';
+export * from './care-emergency-alert-orchestration.js';
 export * from './place-card-association.js';
 export * from './secure-message-crypto.js';

package/docs/CARE_EMERGENCY_AND_ALERT_ORCHESTRATION.md

@@ -0,0 +1,107 @@
+# Care, Emergency and Alert Orchestration
+
+This package owns runtime-neutral authorization and orchestration shared by
+VetChain, UHC and SOSChain. FHIR flat-claim builders belong to
+`fhir-data-utils-ts`; deterministic records belong to `sos-data-utils-ts`;
+transport and persistence belong to BFF/channel and Node services; animal and
+human policy stays in Vet and UHC.
+
+## 1. Care continuity and protected contact
+
+1. Appointment `fulfilled` -> Encounter is an idempotent transition.
+2. The Encounter preserves the selected subject, Appointment, service-provider
+   Organization, start time and current Location.
+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
+   encrypted message to the controller or permitted related recipients before
+   publishing stressful results.
+5. 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;
+   its recipients and thread authorization are revalidated by the service.
+
+The orchestrator returns a plan. The persistence owner must enforce the
+idempotency key and must not treat a returned plan as authorization evidence.
+
+## 2. Resilient emergency assistance
+
+When normal telephone service is unavailable, an authenticated controller or
+authorized requester submits an emergency request to a HealthcareService or
+its owning Organization. The BFF resolves the official target and creates two
+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`. 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,
+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.
+The server evaluates a governed definitional Group, freezes an enumerated Group
+snapshot and binds a CommunicationRequest to that snapshot. Subscription wakes
+evaluation; it is not Consent, cohort-query authority or send authority.
+
+Blood-donation campaigns require compact `system|code` blood-group filters and
+the minimum elapsed days since the last donation. Public-risk campaigns require
+server-authorized FHIR `resourceType`, `searchParameter` and `value` criteria;
+clients cannot submit executable queries.
+
+Immediately before each delivery, the service must verify snapshot membership,
+current eligibility, current exclusions, Consent and channel authorization.
+Only then may it create/send the Communication and record the audit. Group and
+CommunicationRequest resources never replace those per-recipient checks.
+
+## Release proof
+
+Merge validated shared dependency sources to `main`, create immutable
+unpublished tarballs from those commits, and install them temporarily with
+`--no-save`. Prove the affected real local Vet channel (portal, phone service,
+chatbot or another supported channel) -> BFF/channel service -> high-level SDK
+-> GW VET journey without skips. Merge the validated consumer source to
+`main`, publish exact packages bottom-up, pin registry versions, repeat affected
+local gates, and only then promote to staging. Never commit local tarballs or
+local dependency references.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -20,6 +20,10 @@
       "types": "./dist/emergency-group.d.ts",
       "default": "./dist/emergency-group.js"
     },
+    "./care-emergency-alert-orchestration": {
+      "types": "./dist/care-emergency-alert-orchestration.d.ts",
+      "default": "./dist/care-emergency-alert-orchestration.js"
+    },
     "./emergency-authorization": {
       "types": "./dist/emergency-authorization.d.ts",
       "default": "./dist/emergency-authorization.js"
@@ -51,7 +55,8 @@
     "@noble/ciphers": "2.4.0",
     "@noble/hashes": "2.4.0",
     "@noble/post-quantum": "0.7.1",
-    "sos-data-utils-ts": "0.3.9"
+    "fhir-data-utils-ts": "0.3.7",
+    "sos-data-utils-ts": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",