sos-sdk-core-ts 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 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,18 @@ 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, 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.
+
+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,84 @@
+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 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,139 @@
+import { freezeGovernedAlertCohort, normalizeCareJourneyTransition, normalizeEmergencyIntake, normalizeGovernedAlertCampaign, recordGovernedAlertDelivery, } from 'sos-data-utils-ts/care-emergency-alert-records';
+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 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 triageTaskEntry = buildServiceRequestTriageTaskFlatEntry({
+        entryId: intake.triageTaskEntryId,
+        identifier: input.triageTaskIdentifier,
+        serviceRequestReference: serviceRequestEntry.reference,
+        subjectReference: intake.subjectReference,
+        requesterReference: intake.requesterReference,
+        ownerReference: intake.triageOwnerReference,
+        authoredAt: intake.receivedAt,
+    });
+    return Object.freeze({ intake, serviceRequestEntry, triageTaskEntry });
+}
+/** 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 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,74 @@
+# 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`.
+
+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.
+
+## 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.0",
   "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.1"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",